Resolving all symbols in the library
[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 macros MakeMUONZeroMisAlignment.C, MakeMUONResMisAlignment.C
19 and MakeMUONFullMisAlignment.C generate the mis-alignment
20 data (see more in the chapter \ref geometry_s4 below).
21
22 The code can also generate the special geometry 
23 data files, transform.dat and svmap.dat, via the macro  
24 MUONGenerateGeometryData.C (see more in the chapter \ref geometry_s5 below).
25 The svmap.dat data file have to be recreated each time the code 
26 of the geometry is modified. The info (well updated) in this file 
27 is needed during the simulation.
28 We can also decide to use the transform.dat file as input of our 
29 geometry. This allows for changing the position of our detection elements
30 and/or half-planes (half-chambers in code jargon) without modifying 
31 and recompiling the code. 
32
33 Misalignments are in the official AliRoot code applied to the geometry.root
34 file.
35
36
37 \section geometry_s2 How to check the geometry with the Root geometrical modeler
38
39 \see ftp://root.cern.ch/root/doc/chapter16.pdf
40 \see http://agenda.cern.ch/fullAgenda.php?ida=a05212
41
42 <pre>
43 TGeoManager::Import("geometry.root");
44 gGeoManager->GetMasterVolume()->Draw();
45 </pre>
46
47 A helper macro for adding and removing volumes in the
48 scene, MUONGeometryViewingHelper.C is also available.
49  
50
51 \section geometry_s3  How to check the overlaps with the Root geometrical modeler
52
53 \see  ftp://root.cern.ch/root/doc/chapter16.pdf
54 \see  http://agenda.cern.ch/fullAgenda.php?ida=a05212
55
56 <pre>
57 TGeoManager::Import("geometry.root");
58 gGeoManager->CheckOverlaps(0.001);
59 gGeoManager->PrintOverlaps();
60 </pre>
61
62 More extensive, but also more time consuming checking,
63 can be performed in this way:
64 <pre>
65 gGeoManager->CheckGeometryFull(1000000,0,0,0,"o"); >& check_full.out
66 </pre>
67 Then, you will find in the output file \em check_full.out the list of
68 volumes where any overlaps have been detected. As TGeoManager
69 does not remember all overlaps found during checking,
70 in order to investigate them, one has to re-run the checking for 
71 each listed volume:
72 <pre>
73 gGeoManager->FindVolumeFast("MyVolume")->CheckOverlaps(0.001, "s");
74 gGeoManager->PrintOverlaps(); >& overlaps_MyVolume.txt 
75 </pre>
76 At this stage the overlaps found for the selected volume can be also browsed 
77 with TBrowser. Sometimes it happens that the reported overlapping
78 volumes are assemblies and nothing is visualized on the scene
79 when clicking on the overlap icon in the browser.
80 In this case you can use the function setDaughtersVisibility()
81 from the MUONGeometryViewingHelper.C macro, which propagates the
82 visibility setting through all assembly levels up to the real
83 volumes.
84
85 \section geometry_s4 Macro  MUONGenerateGeometryData.C
86                                                 
87 Macro for generating the geometry data files:
88 - MUON/data/svmap.dat file contains all the information to link 
89 each geant volume (it can be extended to other virtual MC) with
90 a detection element. The point here is that a given detection
91 element, i.e. a slat chamber can consist of more geant volumes.
92 the correspondence is then defined in an input file.
93 Each time there is a change in the definition of MC geometry, these
94 input files must be re-generated via the macro  
95 MUONGenerateGeometryData.C
96 - MUON/data/transform.dat file contains the transformations
97 data (translation and rotation) for all alignable objects
98 (modules & detection elements)
99
100 To be run from aliroot:
101 <pre>
102 .x MUONGenerateGeometryData.C
103 </pre>
104
105 The generated files do not replace the existing ones
106 but have different names (with extension ".out").
107 Replacement with new files has to be done manually.
108
109
110 \section geometry_s5 Macros to generate Mis-alignment data
111                                                 
112 Macros for generating the geometry mis-alignment data: 
113 - MakeMUONFullMisAlignment.C
114 - MakeMUONResMisAlignment.C
115 - MakeMUONZeroMisAlignment.C
116
117 To be run from aliroot:
118 <pre>
119 .x MakeMUONFullMisAlignment.C
120 </pre>
121
122 etc.
123
124 If the environment variable TOCDB is not set to "kTRUE",
125 the misalignment data are generated in a local file:
126 MUONfullMisalignment.root, etc.
127
128 If the data are stored in CDB, the storage can be specified in 
129 the environment variable STORAGE. The misalignment data are then
130 generated in the CDB folder (defaults are ResMisAlignCDB and FullMisAlignCDB
131 in the working directory). Inside the local CDB the path for the
132 alignment data is (and must be) "MUON/Align/Data/".
133 Residual misalignment: Default is our current estimate of
134 misalignment after all our alignment procedure has been applied.
135 Full misalignment: Default is our current estimate of initial
136 misalignment.
137
138 The mis-alignment data can be then retrieved from a file
139 and applied to ideal geometry in this way.
140
141 <pre>
142 TGeoManager::Import("geometry.root");
143 TFile f("MUONfullMisalignment.root"); 
144 TClonesArray* misAlignObjsArray = (TClonesArray*)f.Get("MUONAlignObjs");
145 AliGeomManager::ApplyAlignObjsToGeom(*misAlignObjsArray);
146 </pre>
147
148 Mis-aligned geometry can be then inspected in the same
149 way as described in the chapters \ref geometry_s2 and \ref geometry_s3. 
150
151 \section geometry_s6 How to check the alignment software
152
153 The script AlirootRun_MUONtestAlign.sh  allows you to check the software for
154 the alignment with physics tracks. The script will:
155 - Generate a misaligned geometry in a local CDB (default FullMisAlignCDB)
156 - Simulate 1000 events using previously misaligned geometry
157 - Reconstruct the events using perfect geometry
158 - Run the alignment code over the above events using MUONAlignment.C
159
160 To run you need to type:
161 <pre>
162 $ALICE_ROOT/MUON/AlirootRun_MUONtestAlign.sh
163 </pre>
164
165 The results of the test are saved in test_align/ directory. The file measShifts.root
166 contains useful graphs for studying the alignment performances. A local CDB
167 containing the realigned geometry is also created (default is ReAlignCDB). The
168 file $ALICE_ROOT/MUON/data/transform2ReAlign.dat contains the
169 transformations describing the realigned geometry to be compared with the
170 used misaligned geometry $ALICE_ROOT/MUON/data/transform2.dat.
171
172 IMPORTANT NOTE: For a useful test of the alignment performances, the
173 order of 100 000 tracks is needed, it is then advisable to generate and
174 reconstruct enough events separately and run MUONAlignment.C providing a file list
175 afterwards.
176
177 \section geometry_s7 Macro MUONCheckMisAligner.C
178
179 The macro MUONCheckMisAligner.C performs the misalignment on an existing muon 
180 arm geometry based on the standard definition of the detector elements.
181
182 To be run from aliroot:
183 <pre>
184 AliMpCDB::LoadMpSegmentation2();
185 .x MUONCheckMisAligner.C
186 </pre>
187
188 It uses AliMUONGeometryAligner : 
189 - Creates a new AliMUONGeometryTransformer and AliMUONGeometryAligner
190 - Loads the geometry from the specified geometry file (default is geometry.root)
191 - Creates a second AliMUONGeometryTransformer by misaligning the existing 
192 one using AliMUONAligner::MisAlign
193
194 User has to specify the magnitude of the alignments, in the Cartesian 
195 co-ordiantes (which are used to apply translation misalignments) and in the
196 spherical co-ordinates (which are used to apply angular displacements)
197
198 User can also set misalignment ranges by hand using the methods : 
199 SetMaxCartMisAlig, SetMaxAngMisAlig, SetXYAngMisAligFactor
200 (last method takes account of the fact that the misalingment is greatest in 
201 the XY plane, since the detection elements are fixed to a support structure
202 in this plane. Misalignments in the XZ and YZ plane will be very small 
203 compared to those in the XY plane, which are small already - of the order 
204 of microns)
205
206 Default behavior generates a "residual" misalignment using gaussian
207 distributions. Uniform distributions can still be used, see 
208 AliMUONGeometryAligner.
209
210 User can also generate module misalignments using SetModuleCartMisAlig
211 and SetModuleAngMisAlig
212 Note : If the detection elements are allowed to be misaligned in all
213 directions, this has consequences for the alignment algorithm, which 
214 needs to know the number of free parameters. Eric only allowed 3 : 
215 x,y,theta_xy, but in principle z and the other two angles are alignable
216 as well.  
217
218
219 \section geometry_s8 Geometry data files format
220  
221 \subsection geometry_s8_sub1 transform.dat
222  
223  List of transformations for chambers geometry modules and detection
224  elements; in format:
225 <pre> 
226  KEY   ID  [nofDE]  pos: posX posY posZ  rot: theX phiX theY phiY theZ phiZ
227   
228  where  KEY  = CH or DE
229         ID   = chamberId or detElemId
230         pos: posX posY posZ  = position in cm
231         rot: theX phiX theY phiY theZ phiZ = rotation angles as in Geant3 in deg
232 </pre>
233
234 \subsection geometry_s8_sub2  svmap.dat
235
236  Map of sensitive volumes to detction element Ids;
237  in format:
238
239 <pre> 
240  KEY  volpath  detElemId
241   
242  where  KEY  = SV
243         volpath   = volume path in format /volname1_copyNo1/volname2_copyNo2/...
244         detElemId = detection element Id
245  </pre>
246
247
248 This chapter is defined in the READMEgeometry.txt file.
249
250 */