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