bug fixed
[u/mrichter/AliRoot.git] / MUON / READMEmapping.txt
1 // $Id$
2
3 /*! 
4
5 \page README_mapping Mapping
6  
7
8 See the detailed description of the mapping package in ALICE-INT-2003-025.
9 Since that time the mapping has been extended for slat and trigger
10 chamber segmentations an later on also to hold the description of the
11 top level connections of detection elements, including information
12 about DDLs, bus patches and also trigger configuration.
13
14 \section mapping_s0  Mapping in OCDB
15   
16 The mapping is everywhere in the MUON code loaded from
17 OCDB. In case the mapping data files are changed, the mapping
18 in OCDB has to be regenerated in this way:
19
20 For changes in mapping/data:
21 <pre>
22 $> rm $ALICE_ROOT/OCDB/MUON/Calib/MappingData/Run0_999999999_v0_s0.root
23 $> cd $ALICE_ROOT/MUON
24 $> aliroot
25 root [0] AliMpCDB::WriteMpData(); 
26 </pre>
27
28 For changes in mapping/data_run:
29 <pre>
30 $> rm $ALICE_ROOT/OCDB/MUON/Calib/MappingRunData/Run0_999999999_v0_s0.root
31 $> cd $ALICE_ROOT/MUON
32 $> aliroot
33 root [0] AliMpCDB::WriteMpRunData(); 
34 </pre>
35
36 Note that mapping has to be loaded from OCDB almost each time
37 when using MUON classes; the loading of mapping depends on
38 the CBD manager state (the current run number, storage ...).
39 The standard way of loading mapping expects the CDB manager
40 in a state well defined beforehand; this way is used in
41 the MUON code:
42 <pre>
43 if ( ! AliMpCDB::LoadDDLStore() ) {
44   AliFatal("Could not access mapping from OCDB !");
45 }
46 </pre>
47 In the same way, you can load AliMpManuStore, when manu serial 
48 numbers are needed:
49 <pre>
50 if ( ! AliMpCDB::LoadManuStore() ) {
51   AliFatal("Could not access run-dependent mapping from OCDB !");
52 }
53 </pre>
54 In the interactive Root session, in case the CDB manager state is 
55 not defined, you can load mapping from the local OCDB files in this 
56 way:
57 <pre>
58 root [0] AliMpCDB::LoadDDLStore2();
59 root [2] AliMpCDB::LoadManuStore2();
60 </pre>
61
62 \section mapping_s1  Graphical User Interface
63   
64 To use the GUI to plot DE segmentation run:
65
66 <pre> 
67 AliMpCDB::LoadDDLStore2();
68 AliMpCDB::LoadManuStore2();
69 new AliMpDEVisu();
70 </pre>
71
72 or
73
74 <pre>
75 AliMpCDB::LoadDDLStore2();
76 AliMpCDB::LoadManuStore2();
77 new AliMpDEVisu(w, h);
78 </pre>
79
80 if you want to change the size of the GUI window.
81 Typical value are:
82 <pre>
83   w = 1200, h = 600 for PC
84   w = 1000, h = 550 for laptop
85 </pre>
86
87 The GUI allows:
88 - drawing motif of a slat/quadrant
89 - search of a given manu (motif) number
90 - draw the channel number for a given manu number by clicking of the motif in canvas
91 - write down in log message informations about the given detection element
92   * DE Id, DE name, 
93   * number of buspatches, manus, manu serials
94 - option to save log message onto disc
95
96 \section mapping_s2 Test macros
97
98 A set of tests macros have been written during the development
99 of the mapping classes. To run these macros:
100
101 <pre>
102    cd ../mapping/macro
103    root
104    root [0] .x testMacroName.C    
105 </pre>
106                    
107
108 \section mapping_s3  Data files in mapping/data
109
110 The directory data in $ALICE_ROOT/MUON/mapping contains files
111 with data which are not supposed to be changed in a long period.
112
113 \subsection mapping_s3_sub1  zones.dat
114
115 Describes layout of zones, rows, row segments, subzones, motifs
116
117 <pre>
118   SECTOR_DATA
119     number of zones  
120     number of rows  
121     direction of constant pad size (X or Y)
122     offset in X direction
123     offset in Y direction
124   
125   ZONE     
126     number of zone  
127     half legth of pad size in x  
128     half legth of pad size in y
129
130   SUBZONE  
131     motif id  
132     motif type_id       
133
134   ROW_SEGMENT  
135     x offset (in number of pads) 
136     y offset (in number of pads) 
137     row number 
138     nof motifs 
139     first motif position Id
140     step to the next motif position Id (+1 or -1)
141 </pre>
142   
143
144 \subsection mapping_s3_sub2  zones_special.dat
145
146 Describes layout of special row segments (with irregular motifs)
147
148 <pre>
149   SECTOR_SPECIAL_DATA
150
151   MOTIF
152     zone id
153     motif id  
154     motif type_id       
155
156   ROW
157     row number
158   
159   PAD_ROWS
160     number of these pad rows in row   
161   
162   PAD_ROW_SEGMENT
163     mumber of pads in the rows segment  
164     motif id  
165     motif position id
166   
167   motifX.dat
168   ----------
169   Describes characteristics of the motif type X
170
171   In lines:
172     Berg number
173     Kapton number
174     Pad number
175     Gassi number
176 </pre>
177
178
179 \subsection mapping_s3_sub3  motifSpecialX.dat
180
181 Describes characteristics of the special motif with motif Id X;
182 the special motif caontains pads of different size
183
184 <pre>
185   In lines:
186     pad index i (in x)
187     pad index j (in y)
188     half legth of pad size in x  
189     half legth of pad size in y
190 </pre>
191   
192 \subsection mapping_s3_sub4  padPosX.dat
193
194 Maps pad numbers used in the motifX.dat files to
195 the local pad indices (i,j)
196
197 <pre>
198   In lines:
199     Pad number
200     pad index i (in x)
201     pad index j (in y)
202 </pre>
203   
204
205 \subsection mapping_s3_sub5  *.pcb files
206
207 Lines starting with # are comments.
208
209 <pre>
210   SIZES PadSizeX PadSizeY SizeX SizeY (cm)
211
212   MOTIF motifType ix iy
213   MOTIF motifType ix iy
214   ...
215 </pre>
216
217 where ix, iy are the local coordinates (in pad unit) of the
218 lower-left corner of the motif (0,0 is the lower-left corner
219 of the PCB).
220
221 PCB *MUST* be described in a rotating way, starting lower-left and 
222 then counter-clockwise, otherwise the manu-to-motif association 
223 (fixed in the slat definition files) will be wrong.
224
225 Note that for "full" PCBs, the SizeX and SizeY are redundant as they could be 
226 computed from the motif alone (but that serves as a cross-check that the motif 
227 pattern given is ok). That's not the case for short or rounded PCB though.
228
229
230 \subsection mapping_s3_sub6  *.slat files
231
232 A slat is defined by the list of its PCB, described starting 
233 from the beam and going outward.
234
235 One PCB per line, preceded by the keyword PCB
236 Other lines not matching this syntax are ignored.
237 After the PCB is the list of manu ids for this PCB.
238
239 Example :
240
241 <pre>
242   PCB X 1-3;24-20;42;44;53
243   PCB X 1-14
244   PCB Y 100-90
245   PCB Z 1;2;3;4;5;6;7;12;120
246 </pre>
247
248 defines a slat with 4 PCBs : XXYZ
249
250 The manu to motif relationship is attached to the fact that we're counting 
251 counter-clockwise, starting on the lower-left of the PCB. (and the pcb files 
252 have to follow this convention to defined their motifs, otherwise all 
253 this won't work).
254
255 Note that the definition of the PCBs have to be in files with extension
256 .pcb (X.pcb, Y.pcb, Z.pcb)
257
258   
259 \subsection mapping_s3_sub7  DetElemIdToBusPatch.dat
260
261 Lines starting with # are comments.
262
263 Contains the detection element identifier with the associated buspatch numbers 
264 and the corresponding DDL identifier.
265 The link between buspatches and DE's is needed on the rawdata level to identify 
266 the type of quadrant/slat to get the corresponding mapping.
267 The DDL id is needed for the rawdata generation only.
268
269 To generate this file, the macro MUONGenerateBusPatch.C could be used.
270
271
272 \subsection mapping_s3_sub8  BusPatchSpecial.dat
273
274 Lines starting with # are comments.
275
276 Contains the list of bus patches which manu readout is
277 not in the standard order. The format:
278
279 <pre>
280 KEYWORD  DDLs  BusPatches [ManuIDs}
281          where KEYWORD = REVERT or EXPLICIT
282 </pre>
283
284 - For the bus patches following the REVERT keyword,
285   the manus are just reordered in a reverted order.
286 - For the bus patches following the EXPLICIT keyword,
287 the manus filled with a standard procedure (using the DetElemIdToBusPatch.dat
288 file) are replaced with the list of manus in this file.
289
290
291 \subsection mapping_s3_sub9  BusPatchLength.dat
292
293 Lines starting with # are comments.
294
295 Contains the list of bus patches and their cable length in meters
296
297 <pre>
298 # DDL 0
299   1  3
300   2  3
301 ...
302 </pre>
303
304
305 \subsection mapping_s3_sub10  crate.dat
306   
307 Muon trigger electronics configuration file (decoded in class 
308 AliMUONTriggerCrateStore) directly copy/paste from the ALICE PRR 
309 ALICE-EN-2003-010. Gives local board number, name, 
310 crate name it belongs to, slot number, and internal switches 
311 (used in the algorithm).
312
313
314 \subsection mapping_s3_sub11  ManuSerialToBin.dat
315
316 Lines starting with # are comments.
317
318 Contains the manu serial number with their associated bin number, injection and calibration gain.
319
320 To compare the bin number with the serial in the CDB database you can run the macro:
321
322 <pre> 
323 AliMpCDB::LoadDDLStore2();
324 .L $ALICE_ROOT/MUON/mapping/macros/MUONCheckManu.C+
325 MUONCheckManu(10, kFALSE);
326 </pre>
327
328 The function has two parameters, the first is the number of the chamber (zero mean all chambers).
329 The macro can create a set of histogramms with the different gain distributions stored into a root file 
330 (second parameter).
331
332 Two files a generated: one with the list of manu per detection element with their associated bin and gain 
333 value, the other with the bad, strange or unidentified serial number.
334
335
336 \section mapping_s4  Data files in mapping/data_run
337
338 The directory data_run in $ALICE_ROOT/MUON/mapping contains files
339 with data which are expected to change during experiment.
340 At present time, there are only files with manu serial numbers:
341
342 \subsection mapping_s4_sub1  deName_manu_dat.dat
343
344 Contains the list of manuIds and their serial numbers.
345
346 <pre> 
347 # Id bp/nbp serial
348 1 bp 4615
349 2 bp 4616
350 ...
351 </pre> 
352
353 \section mapping_s5  Units used
354  
355 Lengths are in centimeters.
356  
357 This chapter is defined in the READMEmapping.txt file.
358
359 */
360