Reorganized README*.txt pages to get them well ordered
[u/mrichter/AliRoot.git] / MUON / READMEgeometry.txt
1 // $Id$
2
3 /*! 
4
5 \page README_geometry Geometry
6
7
8 \section geometry_s1 General Information about MUON Geometry
9
10 Our geometry is described in the geometry builder classes.
11 The main geometrical constants are set in the class AliMUONConstants.
12 The geometry is built from the code during running simulation
13 and it is automatically exported in a geometry.root file
14 via the framework. Then  aliroot takes this geometry.root file as 
15 a unique geometrical info of our apparatus during the generation 
16 and the reconstruction and analysis (if needed)
17
18 The code can also generate the special geometry 
19 data files, transform.dat and svmap.dat, via the macro  
20 MUONGenerateGeometryData.C (see more in \ref geometry_s4 below).
21 The svmap.dat data file have to be recreated each time the code 
22 of the geometry is modified. The info (well updated) in this file 
23 is needed during the simulation.
24 We can also decide to use the transform.dat file as input of our 
25 geometry. This allows for changing the position of our detection elements
26 and/or half-planes (half-chambers in code jargon) without modifying 
27 and recompiling the code. 
28
29 Misalignments are in the official AliRoot code applied to the geometry.root
30 file.
31
32
33 \section geometry_s2 How to check the geometry with the Root geometrical modeler
34
35 \see ftp://root.cern.ch/root/doc/chapter16.pdf
36 \see http://agenda.cern.ch/fullAgenda.php?ida=a05212
37
38 <pre>
39 gAlice->Init("$ALICE_ROOT/MUON/Config.C");
40 gGeoManager->GetMasterVolume()->Draw();
41 </pre>
42
43
44 \section geometry_s3  How to check the overlaps with the Root geometrical modeler
45
46 \see  ftp://root.cern.ch/root/doc/chapter16.pdf
47 \see  http://agenda.cern.ch/fullAgenda.php?ida=a05212
48
49 <pre>
50 gAlice->Init("$ALICE_ROOT/MUON/Config.C");
51 gGeoManager->CheckOverlaps();
52 gGeoManager->PrintOverlaps();
53 </pre>
54
55
56 \section geometry_s4 Macro  MUONGenerateGeometryData.C
57                                                 
58 Macro for generating the geometry data files:
59 - MUON/data/svmap.dat file contains all the information to link 
60 each geant volume (it can be extended to other virtual MC) with
61 a detection element. The point here is that a given detection
62 element, i.e. a slat chamber can consist of more geant volumes.
63 the correspondence is then defined in an input file.
64 Each time there is a change in the definition of MC geometry, these
65 input files must be re-generated via the macro  
66 MUONGenerateGeometryData.C
67 - MUON/data/transform.dat file contains the transformations
68 data (translation and rotation) for all alignable objects
69 (modules & detection elements)
70
71 To be run from aliroot:
72 <pre>
73 .x MUONGenerateGeometryData.C
74 </pre>
75
76 The generated files do not replace the existing ones
77 but have different names (with extension ".out").
78 Replacement with new files has to be done manually.
79
80
81 \section geometry_s5 Macros to generate Mis-alignment data
82                                                 
83 Macros for generating the geometry mis-alignment data: 
84 - MakeMUONFullMisAlignment.C
85 - MakeMUONResMisAlignment.C
86 - MakeMUONZeroMisAlignment.C
87
88 To be run from aliroot:
89 <pre>
90 .x MakeMUONFullMisAlignment.C
91 </pre>
92
93 etc.
94
95 If the environment variable TOCDB is not set to "kTRUE",
96 the misalignment data are generated in a local file:
97 MUONFullMisalignment.root, etc.
98
99 If the data are stored in CDB, the storage can be specified in 
100 the environment variable STORAGE. The misalignment data are then
101 generated in the CDB folder (defaults are ResMisAlignCDB and FullMisAlignCDB
102 in the working directory). Inside the local CDB the path for the
103 alignment data is (and must be) "MUON/Align/Data/".
104 Residual misalignment: Default is our current estimate of
105 misalignment after all our alignment procedure has been applied.
106 Full misalignment: Default is our current estimate of initial
107 misalignment.
108
109
110 \section geometry_s6 How to check the alignment software
111
112 The script AlirootRun_MUONtestAlign.sh  allows you to check the software for
113 the alignment with physics tracks. The script will:
114 - Generate a misaligned geometry in a local CDB (default FullMisAlignCDB)
115 - Simulate 1000 events using previously misaligned geometry
116 - Reconstruct the events using perfect geometry
117 - Run the alignment code over the above events using MUONAlignment.C
118
119 To run you need to type:
120 <pre>
121 $ALICE_ROOT/MUON/AlirootRun_MUONtestAlign.sh
122 </pre>
123
124 The results of the test are saved in test_align/ directory. The file measShifts.root
125 contains useful graphs for studying the alignment performances. A local CDB
126 containing the realigned geometry is also created (default is ReAlignCDB). The
127 file $ALICE_ROOT/MUON/data/transform2ReAlign.dat contains the
128 transformations describing the realigned geometry to be compared with the
129 used misaligned geometry $ALICE_ROOT/MUON/data/transform2.dat.
130
131 IMPORTANT NOTE: For a useful test of the alignment performances, the
132 order of 100 000 tracks is needed, it is then advisable to generate and
133 reconstruct enough events separately and run MUONAlignment.C providing a file list
134 afterwards.
135
136 \section geometry_s7 Macro MUONCheckMisAligner.C
137
138 The macro MUONCheckMisAligner.C performs the misalignment on an existing muon 
139 arm geometry based on the standard definition of the detector elements.
140
141 It uses AliMUONGeometryAligner : 
142 - Creates a new AliMUONGeometryTransformer and AliMUONGeometryAligner
143 - Reads the transformations in from the transform.dat file (make sure that
144 this file is the _standard_ one by comparing it to the one in CVS)
145 - Creates a second AliMUONGeometryTransformer by misaligning the existing 
146 one using AliMUONAligner::MisAlign
147
148 User has to specify the magnitude of the alignments, in the Cartesian 
149 co-ordiantes (which are used to apply translation misalignments) and in the
150 spherical co-ordinates (which are used to apply angular displacements)
151
152 User can also set misalignment ranges by hand using the methods : 
153 SetMaxCartMisAlig, SetMaxAngMisAlig, SetXYAngMisAligFactor
154 (last method takes account of the fact that the misalingment is greatest in 
155 the XY plane, since the detection elements are fixed to a support structure
156 in this plane. Misalignments in the XZ and YZ plane will be very small 
157 compared to those in the XY plane, which are small already - of the order 
158 of microns)
159
160 Default behavior generates a "residual" misalignment using gaussian
161 distributions. Uniform distributions can still be used, see 
162 AliMUONGeometryAligner.
163
164 User can also generate module misalignments using SetModuleCartMisAlig
165 and SetModuleAngMisAlig
166 Note : If the detection elements are allowed to be misaligned in all
167 directions, this has consequences for the alignment algorithm, which 
168 needs to know the number of free parameters. Eric only allowed 3 : 
169 x,y,theta_xy, but in principle z and the other two angles are alignable
170 as well.  
171
172
173 \section geometry_s8 Geometry data files format
174  
175 \subsection geometry_s8_sub1 transform.dat
176  
177  List of transformations for chambers geometry modules and detection
178  elements; in format:
179 <pre> 
180  KEY   ID  [nofDE]  pos: posX posY posZ  rot: theX phiX theY phiY theZ phiZ
181   
182  where  KEY  = CH or DE
183         ID   = chamberId or detElemId
184         pos: posX posY posZ  = position in cm
185         rot: theX phiX theY phiY theZ phiZ = rotation angles as in Geant3 in deg
186 </pre>
187
188 \subsection geometry_s8_sub2  svmap.dat
189
190  Map of sensitive volumes to detction element Ids;
191  in format:
192
193 <pre> 
194  KEY  volpath  detElemId
195   
196  where  KEY  = SV
197         volpath   = volume path in format /volname1_copyNo1/volname2_copyNo2/...
198         detElemId = detection element Id
199  </pre>
200
201
202 This chapter is defined in the READMEgeometry.txt file.
203
204 */