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