--- /dev/null
+1. Introduction
+---------------
+
+Dear ITS (and ALICE) user,
+
+this is a short help on how to run the ITS simulation/reconstruction code
+within the AliRoot framework. It is NOT intended as a comprehensive user's
+guide and eventually it will be updated in the ITS Manual which is on its way
+to be written. What follows requires that the you already know how to download,
+install and compile the AliRoot package. This file explains how to set the
+proper ITS geometry and how to tun the test macros contained under the
+directory ITS in order to compare your own installation with the standard one
+looking at some distributions/histograms.
+Any difference between what is described here and what you really get when you
+run the code on your computer must be reported to Roberto Barbera at
+roberto.barbera@ct.infn.it. Please note that all the tests described here have
+been done on a PC running Linux RedHat 6.1, gcc 2.95.2, and Root 3.00/06.
+If you have different hardware/software configuration, please add it to all bug
+reports.
+
+
+2. Set the ITS geometry you want to use
+---------------------------------------
+
+In order to set one of the many ITS geometries available, you have to modify
+the ITS part in the file Config.C under the directory macros (you have to modify
+the file ConfigPPR.C if you want to run full 'PPR' events). The default ITS
+part of Config.C (or ConfigPPR.C) is reported here:
+
+ if(iITS) {
+
+//=================== ITS parameters ============================
+ //
+ // As the innermost detector in ALICE, the Inner Tracking System "impacts" on
+ // almost all other detectors. This involves the fact that the ITS geometry
+ // still has several options to be followed in parallel in order to determine
+ // the best set-up which minimizes the induced background. All the geometries
+ // available to date are described in the following. Read carefully the comments
+ // and use the default version (the only one uncommented) unless you are making
+ // comparisons and you know what you are doing. In this case just uncomment the
+ // ITS geometry you want to use and run Aliroot.
+ //
+ // Detailed geometries:
+ //
+ //
+ //
+ //
+ //AliITS *ITS = new AliITSv5symm("ITS","Updated ITS TDR detailed version with symmetric services");
+ //
+ AliITS *ITS = new AliITSv5asymm("ITS","Updates ITS TDR detailed version with asymmetric services");
+ //
+ //AliITSvPPRasymm *ITS = new AliITSvPPRasymm("ITS","New ITS PPR detailed version with asymmetric services");
+ //ITS->SetMinorVersion(2);
+ //ITS->SetReadDet(kFALSE);
+ //ITS->SetWriteDet("$ALICE_ROOT/ITS/ITSgeometry_vPPRasymm2.det");
+ //ITS->SetThicknessDet1(300.); // detector thickness on layer 1 must be in the range [100,300]
+ //ITS->SetThicknessDet2(300.); // detector thickness on layer 2 must be in the range [100,300]
+ //ITS->SetThicknessChip1(300.); // chip thickness on layer 1 must be in the range [150,300]
+ //ITS->SetThicknessChip2(300.); // chip thickness on layer 2 must be in the range [150,300]
+ //ITS->SetRails(1); // 1 --> rails in ; 0 --> rails out
+ //ITS->SetCoolingFluid(1); // 1 --> water ; 0 --> freon
+ //
+ //AliITSvPPRsymm *ITS = new AliITSvPPRsymm("ITS","New ITS PPR detailed version with symmetric services");
+ //ITS->SetMinorVersion(2);
+ //ITS->SetReadDet(kFALSE);
+ //ITS->SetWriteDet("$ALICE_ROOT/ITS/ITSgeometry_vPPRsymm2.det");
+ //ITS->SetThicknessDet1(300.); // detector thickness on layer 1 must be in the range [100,300]
+ //ITS->SetThicknessDet2(300.); // detector thickness on layer 2 must be in the range [100,300]
+ //ITS->SetThicknessChip1(300.); // chip thickness on layer 1 must be in the range [150,300]
+ //ITS->SetThicknessChip2(300.); // chip thickness on layer 2 must be in the range [150,300]
+ //ITS->SetRails(1); // 1 --> rails in ; 0 --> rails out
+ //ITS->SetCoolingFluid(1); // 1 --> water ; 0 --> freon
+ //
+ //
+ // Coarse geometries (warning: no hits are produced with these coarse geometries and they unuseful
+ // for reconstruction !):
+ //
+ //
+ //
+ //AliITSvPPRcoarseasymm *ITS = new AliITSvPPRcoarseasymm("ITS","New ITS coarse version with asymmetric services");
+ //ITS->SetRails(1); // 1 --> rails in ; 0 --> rails out
+ //ITS->SetSupportMaterial(0); // 0 --> Copper ; 1 --> Aluminum ; 2 --> Carbon
+ //
+ //AliITS *ITS = new AliITSvPPRcoarsesymm("ITS","New ITS coarse version with symmetric services");
+ //ITS->SetRails(1); // 1 --> rails in ; 0 --> rails out
+ //ITS->SetSupportMaterial(0); // 0 --> Copper ; 1 --> Aluminum ; 2 --> Carbon
+ //
+ //
+ //
+ // Geant3 <-> EUCLID conversion
+ // ============================
+ //
+ // SetEUCLID is a flag to output (=1) or not to output (=0) both geometry and
+ // media to two ASCII files (called by default ITSgeometry.euc and
+ // ITSgeometry.tme) in a format understandable to the CAD system EUCLID.
+ // The default (=0) means that you dont want to use this facility.
+ //
+ ITS->SetEUCLID(0);
+ }
+
+As you can see looking at the uncommented line, the present default is
+
+ AliITS *ITS = new AliITSv5asymm("ITS","Updates ITS TDR detailed version with asymmetric services");
+
+which is the TDR detailed geometry with asymmetric services.
+If you want to run the TDR detailed version with symmetric services, the only
+uncommented line must be:
+
+ AliITS *ITS = new AliITSv5symm("ITS","Updated ITS TDR detailed version with symmetric services");
+
+If you want to run the new PPR coarse geometry with asymmetric services, the
+only uncommented lines must be:
+
+ AliITSvPPRcoarseasymm *ITS = new AliITSvPPRcoarseasymm("ITS","New ITS coarse version with asymmetric services");
+ ITS->SetRails(1); // 1 --> rails in ; 0 --> rails out
+ ITS->SetSupportMaterial(0); // 0 --> Copper ; 1 --> Aluminum ; 2 --> Carbon
+
+If you want to run the new PPR coarse geometry with symmetric services, the
+only uncommented lines must be:
+
+ AliITS *ITS = new AliITSvPPRcoarsesymm("ITS","New ITS coarse version with symmetric services");
+ ITS->SetRails(1); // 1 --> rails in ; 0 --> rails out
+ ITS->SetSupportMaterial(0); // 0 --> Copper ; 1 --> Aluminum ; 2 --> Carbon
+
+If you want to run the new PPR detailed geometry with asymmetric services, the
+only uncommented lines must be:
+
+ AliITSvPPRasymm *ITS = new AliITSvPPRasymm("ITS","New ITS PPR detailed version with asymmetric services");
+ ITS->SetMinorVersion(2);
+ ITS->SetReadDet(kFALSE);
+ ITS->SetWriteDet("$ALICE_ROOT/ITS/ITSgeometry_vPPRasymm2.det");
+ ITS->SetThicknessDet1(300.); // detector thickness on layer 1 must be in the range [100,300]
+ ITS->SetThicknessDet2(300.); // detector thickness on layer 2 must be in the range [100,300]
+ ITS->SetThicknessChip1(300.); // chip thickness on layer 1 must be in the range [150,300]
+ ITS->SetThicknessChip2(300.); // chip thickness on layer 2 must be in the range [150,300]
+ ITS->SetRails(1); // 1 --> rails in ; 0 --> rails out
+ ITS->SetCoolingFluid(1); // 1 --> water ; 0 --> freon
+
+If you want to run the new PPR detailed geometry with symmetric services, the
+only uncommented lines must be:
+
+ AliITSvPPRsymm *ITS = new AliITSvPPRsymm("ITS","New ITS PPR detailed version with symmetric services");
+ ITS->SetMinorVersion(2);
+ ITS->SetReadDet(kFALSE);
+ ITS->SetWriteDet("$ALICE_ROOT/ITS/ITSgeometry_vPPRsymm2.det");
+ ITS->SetThicknessDet1(300.); // detector thickness on layer 1 must be in the range [100,300]
+ ITS->SetThicknessDet2(300.); // detector thickness on layer 2 must be in the range [100,300]
+ ITS->SetThicknessChip1(300.); // chip thickness on layer 1 must be in the range [150,300]
+ ITS->SetThicknessChip2(300.); // chip thickness on layer 2 must be in the range [150,300]
+ ITS->SetRails(1); // 1 --> rails in ; 0 --> rails out
+ ITS->SetCoolingFluid(1); // 1 --> water ; 0 --> freon
+
+
+3. Simulation
+-------------
+
+In order to run an event with a given ITS geometry put yourself in the directory
+macros and do the following:
+
+- interactive run: start aliroot and the type the command "gAlice->Run()".
+ At the end of the run exit from aliroot with the command ".q".
+- batch run: type the shell command "aliroot -q -b grun.C >& fileout &" where
+ fileout is a name at your choice of the file where you want to store output
+ and error messages.
+
+In principle there is another way to run aliroot using the script alirun but
+this is not described here.
+Aliroot creates an output root file always called galice.root. If you want to
+run the ITS reconstruction code, copy/move this file in the directory ITS and
+read the following instructions.
+
+
+4. Cluster finding (fast)
+-------------------------
+
+Reconstructed points in the space can be calculated either smearing the Geant3
+hits according with the various detector resolutions and applying the
+thresholds for all detectors (fast reconstruction or, for short, "fast points"),
+or performing a cluster finding after the detector digitization (slow
+reconstruction or, for short, "slow points"). Fast point creation is described
+here while slow point one is described in sections 5 and 6.
+From now on, we assume that you are under the directory ITS. If it is the case
+you can do the following:
+
+- interactive run: start aliroot and the type the command
+ ".x ITSHitsToFastPoints.C". At the end of the run exit from aliroot with the
+ command ".q".
+- batch run: type the shell command
+ "aliroot -q -b ITSHitsToFastPoints.C >& fileout &" where fileout is a name at
+ your choice of the file where you want to store output and error messages.
+
+Fast points are written in the same galice.root file as you can see issuing the
+shell command "ls -l galice.root" before and after their creation and looking at
+the size of the root file.
+By default, fast points are created for all kind of ITS subdetectors (SPD, SDD,
+and SSD). This is done with the function call:
+
+ ITS->HitsToFastRecPoints(ev,bgr_ev,size," ","All"," ");
+
+in the macro ITSHitsToFastPoints.C. If you want to create fast points only for
+one type of subdectors you have to substitute the string "All" in the above
+function call with "SPD", "SDD", or "SSD". Normal users are, however, strongly
+encouraged to create the "fast points" for all subdetectors at once not touching
+the macro ITSHitsToFastPoints.C.
+Fast points are intended only for tests. Normal users are also strongly
+encouraged to run the complete ITS reconstruction described in the next two
+sections.
+
+
+5. Digitization
+---------------
+
+In order to run the ITS digitization, put yourself under ITS and do the
+following:
+
+- interactive run: start aliroot and the type the command
+ ".x ITSHitsToDigits.C". At the end of the run exit from aliroot with the
+ command ".q".
+- batch run: type the shell command
+ "aliroot -q -b ITSHitsToDigits.C >& fileout &" where fileout is a name at
+ your choice of the file where you want to store output and error messages.
+
+Digits are written in the same galice.root file as you can see issuing the
+shell command "ls -l galice.root" before and after their creation and looking at
+the size of the root file.
+By default, digits are created for all kind of ITS subdetectors (SPD, SDD,
+and SSD). This is done with the function call:
+
+ ITS->HitsToDigits(nev,nbgr_ev,size," ","All"," ");
+
+in the macro ITSHitsToDigits.C. If you want to create digits only for
+one type of subdectors you have to substitute the string "All" in the above
+function call with "SPD", "SDD", or "SSD". Normal users are, however, strongly
+encouraged to run the ITS digitization for all subdetectors at once not touching
+the macro ITSHitsToDigits.C.
+By default the so-called "Dubna simulation" of the pixel detectors is
+performed. In order to run the "Bari simulation" of the pixel detectors (waiting
+for the merging of the two) you have to use the macro ITSHitsToDigitsBari.C.
+
+
+6. Cluster finding (slow)
+-------------------------
+
+In order to perform the cluster finding and create the "slow points", do the
+following:
+
+- interactive run: start aliroot and the type the command
+ ".x ITSDigitsToClusters.C". At the end of the run exit from aliroot with the
+ command ".q".
+- batch run: type the shell command
+ "aliroot -q -b ITSDigitsToClusters.C >& fileout &" where fileout is a name at
+ your choice of the file where you want to store output and error messages.
+
+Slow points are written in the same galice.root file as you can see issuing the
+shell command "ls -l galice.root" before and after their creation and looking at
+the size of the root file.
+By default, slow points are created for all kind of ITS subdetectors (SPD, SDD,
+and SSD). This is done with the function call:
+
+ ITS->DigitsToRecPoints(nev,last_entry,"All");
+
+in the macro ITSDigitsToClusters.C. If you want to create slow points only for
+one type of subdectors you have to substitute the string "All" in the above
+function call with "SPD", "SDD", or "SSD". Normal users are, however, strongly
+encouraged to create the slow points for all subdetectors at once not touching
+the macro ITSDigitsToClusters.C.
+By default the so-called "Dubna reconstruction" of the pixel detectors is
+performed. In order to run the "Bari reconstruction" of the pixel detectors
+(waiting for the merging of the two) you have to use the macro
+ITSDigitsToClustersBari.C.
+
+
+7. Useful test macros
+---------------------
+
+Once you have created digits and slow points, you can now run some useful test
+macros. They can also be used as useful starting point to understand how to read
+hits, digits and points back from the galice.root file. The macros are listed
+below together with some help on their use. Some of the macros produce output
+graphics, so the suggestion is to run them interactively starting aliroot and
+then typing the command ".x macro.C" at the aliroot prompt.
+
+- SPDclusterTest.C: this macro opens the galice.root file, reads the
+reconstructed points and plots the SPD resolution both for layer 1 and 2, in Z
+and Rphi direction. Moreover, it creates the Root file SPD_his.root which
+contains some useful histograms and nt-uples which can be read back with the
+macro SPD_ntuple.C.
+
+- ITSreadClustTestSPD.C: this macros opens the galice.root, reads SPD digits and
+prints them on the screen.
+
+- ITSsddanalysis.C: this macro opens the galice.root file, performs some
+analysis of the drift detectors and creates the Root output file
+SDD_histos_test.root. This output file can then be read by the macro
+ITSsddtest.C which create some PostScript file containing reference histograms.
+
+- SSDrecpointTest.C: this macro opens the galice.root file, reads the
+reconstructed points and plots the SSD resolution both for layer 5 and 6, in Z
+and Rphi direction. Moreover, it creates the Root file SSD_his.root which
+contains some useful histograms and nt-uples which can be read back with the
+macro SSD_ntuple.C.
+
+- ITSreadRecPointsTest.C: this macro opens the galice.root file, reads the
+reconstructed points and prints them on the screen for all ITS modules. For each
+reconstructed point the following quantities are printed: the recpoint index in
+the module (0, 1, 2, ...), the X coordinate in the local reference system of the
+module, the Z coordinate in the local reference system of the module, three
+integers indicating the id numbers of the tracks contributing to that
+reconstructed point. Only positive numbers, of course, are real tracks. Negative
+numbers (-1 for SPD, -3 for SDD, and -2 for SSD) are just there to fill the
+vector of track id's associated to a given reconstructed point.
+
+- ITSgeoplot.C: this macro opens the galice.root file, reads hits, digits and
+recpoint for SPD, SDD and SSD and plots them in the global reference system.
+
+- ITSReadPlotData.C: this macros opens the galice.root file and then prompts the
+user for an ITS module identified by layer, ladder and detector or by the unique
+ID. That module is then searched for hits, digits and
+reconstructed points and they are plotted in the local reference frame of the
+module with different symbols.
+
+
+8. Occupancy
+------------
+
+ITS occupancy can be evaluated by the macro ITSOccupancy.C which opens the
+galice.root files, reads the number of digits for all subdetectors, and
+calculate the occupancy as the ratio of the "fired" digits over the total number
+of digits. Plots are also created showing the occupancy as a function of the Z
+coordinate along the beams' axis. In order to increase the speed of the
+calculation the macro is compilable. See the comments in the code about how to
+run it.
+
git://git.uio.no / u / mrichter / AliRoot.git / commitdiff