Adding PiKP-only histograms and eliminating a number of switches where histograms...
[u/mrichter/AliRoot.git] / MUON / READMEraw.txt
1 // $Id$
2
3 /*! 
4
5 \page README_raw Raw data
6  
7 \section raw_s1 How to read & decode raw data 
8
9 The macros MUONRawStreamTracker.C and MUONRawStreamTrigger.C can 
10 be used to read & decode DDL files and root files.
11 DATE files are no more supported.
12
13 For tracker raw data, full output
14 <pre>
15 .includepath $ALICE_ROOT/STEER
16 .includepath $ALICE_ROOT/MUON
17 .includepath $ALICE_ROOT/RAW
18 .L $ALICE_ROOT/MUON/MUONRawStreamTracker.C+
19 MUONRawStreamTrackerExpert(rawFileName, maxEvent, firstDDL, lastDDL)
20 </pre>
21
22 For tracker raw data, just digit output
23 <pre>
24 .includepath $ALICE_ROOT/STEER
25 .includepath $ALICE_ROOT/MUON
26 .includepath $ALICE_ROOT/RAW
27 .L $ALICE_ROOT/MUON/MUONRawStreamTracker.C+
28 MUONRawStreamTrackerSimple(rawFileName, maxEvent, firstDDL, lastDDL)
29 </pre>
30
31 There is also a high performance decoder available, which can be run as follows
32 for full output:
33 <pre>
34 .includepath $ALICE_ROOT/STEER
35 .includepath $ALICE_ROOT/MUON
36 .includepath $ALICE_ROOT/RAW
37 .L $ALICE_ROOT/MUON/MUONRawStreamTracker.C+
38 MUONRawStreamTrackerHPExpert(rawFileName, maxEvent, firstDDL, lastDDL)
39 </pre>
40
41 And just for digit output like so:
42 <pre>
43 .includepath $ALICE_ROOT/STEER
44 .includepath $ALICE_ROOT/MUON
45 .includepath $ALICE_ROOT/RAW
46 .L $ALICE_ROOT/MUON/MUONRawStreamTracker.C+
47 MUONRawStreamTrackerHPSimple(rawFileName, maxEvent, firstDDL, lastDDL)
48 </pre>
49
50 The MUONRawStreamTracker.C macro also provides other alternative implementations
51 for fetching the decoded data from the high performance decoder's interface.
52 These generate the same output, but show how to write code to fetch the data in
53 various ways from the interface. Developers should consult the macro as an example
54 of how to use the interface. The alternate methods are called:
55 <pre>
56 MUONRawStreamTrackerHPExpert2()
57 MUONRawStreamTrackerHPExpert3()
58 MUONRawStreamTrackerHPSimple2()
59 </pre>
60
61
62 For trigger raw data, full output
63 <pre>
64 .includepath $ALICE_ROOT/STEER
65 .includepath $ALICE_ROOT/MUON
66 .includepath $ALICE_ROOT/RAW
67 .L $ALICE_ROOT/MUON/MUONRawStreamTrigger.C+ 
68 MUONRawStreamTrigger(maxEvent, firstDDL, lastDDL, rawFileName)
69 </pre>
70
71 For trigger raw data, local response output
72 <pre>
73 .includepath $ALICE_ROOT/STEER
74 .includepath $ALICE_ROOT/MUON
75 .includepath $ALICE_ROOT/RAW
76 .L $ALICE_ROOT/MUON/MUONRawStreamTrigger.C+ 
77 MUONRawStreamTriggerSimple(maxEvent, rawFileName)
78 </pre>
79
80 Similarly there is a high performance decoder available for the trigger DDLs,
81 which can be run as follows for full output:
82 <pre>
83 .includepath $ALICE_ROOT/STEER
84 .includepath $ALICE_ROOT/MUON
85 .includepath $ALICE_ROOT/RAW
86 .L $ALICE_ROOT/MUON/MUONRawStreamTrigger.C+
87 MUONRawStreamTriggerHPExpert(maxEvent, firstDDL, lastDDL, rawFileName)
88 </pre>
89
90 And just for local response output like so:
91 <pre>
92 .includepath $ALICE_ROOT/STEER
93 .includepath $ALICE_ROOT/MUON
94 .includepath $ALICE_ROOT/RAW
95 .L $ALICE_ROOT/MUON/MUONRawStreamTrigger.C+
96 MUONRawStreamTriggerHPSimple(maxEvent, rawFileName)
97 </pre>
98
99 The MUONRawStreamTrigger.C macro also provides other alternative implementations
100 for fetching the decoded data from the trigger high performance decoder's interface.
101 These generate the same output, but show how to write code to fetch the data in
102 various ways from the interface. Developers should consult the macro as an example
103 of how to use the interface. The alternate methods are called:
104 <pre>
105 MUONRawStreamTriggerHPExpert2()
106 MUONRawStreamTriggerHPExpert3()
107 MUONRawStreamTriggerHPSimple2()
108 </pre>
109
110
111 Default wise the macros read all DDL files from the current directory for 1000 events.
112 For root file rawFileName must end with .root. For DDL files you have to specified the directory 
113 where the raw0...n subdirectories are located:
114 <pre>
115 MUONRawStreamTracker(..)(maxEvent, firstDDL, lastDDL, "$YOUR_WORKING_DIRECTORY/"); //Do not forget the slash at the end!
116 </pre>
117
118 \section raw_s2 Timing of the raw data decoders
119
120 The macro MUONTimeRawStreamTracker.C and MUONTimeRawStreamTrigger.C can used to
121 check the timing (speed) performance of the existing offline decoders compared to
122 the new high performance decoders.
123 For the tracker DDLs the MUONTimeRawStreamTracker.C macro compares the timing of
124 AliMUONRawStreamTracker against the high performance AliMUONRawStreamTrackerHP
125 decoder.
126 Similarly the MUONTimeRawStreamTrigger.C macro compares the timing of the
127 existing AliMUONRawStreamTrigger decoder against the high performance
128 AliMUONRawStreamTrackerHP decoder.
129 The macros can be invoked as follows:
130
131 <pre>
132  $ aliroot
133 .L $ALICE_ROOT/MUON/MUONTimeRawStreamTracker.C+
134  MUONTimeRawStreamTracker(filename, maxEvent);
135 .L $ALICE_ROOT/MUON/MUONTimeRawStreamTrigger.C+
136  MUONTimeRawStreamTrigger(filename, maxEvent);
137 </pre>
138
139 where \em filename is the name of a file containing the raw data, or alternatively
140 the directory containing rawX (X being an integer) paths with the raw DDL
141 data. The \em maxEvent value is the maximum event to process (default set to
142 1000). Thus the macro will time the algorithm for all events in the range
143 [0 .. maxEvent-1].
144
145
146 \section raw_s3 Special flags for high performance tracker and trigger DDL decoders.
147
148 There are three flags that are available through the AliMUONRawStreamTrackerHP
149 interface, which effect the decoding of raw data in special ways.
150 \li TryRecover (default = false)
151 \li AutoDetectTrailer (default = true)
152 \li CheckForTrailer  (default = true)
153
154 The TryRecover flag is used to enable special logic in the decoder that tries
155 to recover from a partially corrupt raw data structure header, or a corrupt/missing
156 end of DDL trailer. Normally if the header is found to be corrupt (by seeing
157 that the block lengths do not correspond),
158 then the whole corresponding structure is skipped and we move on to the
159 next structure that we are sure of, or skip the rest of the DDL.
160 With the option to recover turned on, we attempt to figure out what the correct
161 values for the structure length should have been. This is possible because there
162 is redundant information in the headers giving the structure size. This recovery
163 procedure will work for single bit flips found inside the headers, but obviously
164 with more severe corruption, the header will not be recoverable.
165 The TryRecover flag is set to kFALSE by default to disable this feature, meaning
166 any structures in the raw data that cause problems in any way are skipped by
167 default. More details about the corrupt header recovery procedure can be found
168 in the method documentation AliMUONTrackerDDLDecoder::TryRecoverStruct().
169
170 The AutoDetectTrailer and CheckForTrailer flags are used to deal with the
171 difference in raw data format from the real tracker chambers and the simulated
172 data generated with AliRoot up to March 2008. The end of DDL trailer words are
173 missing in the simulated raw data in the older versions of AliRoot. To tell the
174 decoder that it should expect the trailer words as generated by the real readout
175 electronics then the CheckForTrailer flag should be set to kTRUE (this is the
176 default). If the trailer words are missing in the raw data then CheckForTrailer
177 should be kFALSE. Alternatively one can set the flag AutoDetectTrailer to kTRUE
178 (which is the default) so that the decoder will try to autodetect if the trailer
179 words are there or not. When AutoDetectTrailer is set to kTRUE then the
180 CheckForTrailer flag is ignored. Only when AutoDetectTrailer is set to kFALSE
181 will the CheckForTrailer flag have an effect.
182
183 Each of these decoder flags can be set to kTRUE or kFALSE, or tested by the
184 corresponding setter and getter methods respectively. For example, to set the
185 TryRecover flag to kTRUE and fetch its value afterwards, use the following code:
186 \code
187 AliMUONRawStreamTrackerHP decoder;
188 // to set the flag:
189 decoder.TryRecover(kTRUE);
190 // or to get the value of the flag:
191 Bool_t value = decoder.TryRecover();
192 \endcode
193 Similarly, the other flags are manipulated with corresponding methods having
194 the same name as the flag.
195
196 The trigger DDL decoder AliMUONRawStreamTriggerHP has the following flag available:
197 \li TryRecover (default = false)
198
199 For the AliMUONRawStreamTriggerHP decoder the TryRecover flag can be set in the
200 same way as for AliMUONRawStreamTrackerHP, with a call to the TryRecover() method.
201 For trigger DDLs this option will enable logic, which attempts to find the next
202 correct header / structure marker key in the DDL stream, whenever such a marker
203 has been found corrupt or missing. Decoding then continues from the new location
204 found or stops if no good key was found. The default setting is to disable this
205 logic, since it is only useful to try recover corrupted data.
206
207 \note Raw data containing software scalars (Start-of-Data events for example)
208 from the trigger detector taken during the Feb-March 2008 cosmics run is corrupt,
209 but can be successfully decoded by enabling this TryRecover flag for the
210 trigger DDL decoder.
211
212
213 This chapter is defined in the READMEraw.txt file.
214
215 */
216