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, firstDDL, lastDDL, rawFileName)
  78 </pre>
  79
  80
  81 Default wise the macro read all DDL files from the current directory for 1000 events.
  82 For root file rawFileName must end with .root. For DDL files you have to specified the directory
  83 where the raw0...n subdirectories are located:
  84 <pre>
  85 MUONRawStreamTracker(..)(maxEvent, firstDDL, lastDDL, "$YOUR_WORKING_DIRECTORY/"); //Do not forget the slash at the end!
  86 </pre>
  87
  88 \section raw_s2 Timing of the raw data decoders
  89
  90 The macro MUONTimeRawStreamTracker.C can used to check the timing (speed) performance
  91 of the existing offline decoder for the tracker DDLs (AliMUONRawStreamTracker) and also
  92 for the new high performance decoder (AliMUONRawStreamTrackerHP). It can be invoked
  93 as follows:
  94
  95 <pre>
  96  $ aliroot
  97 .L $ALICE_ROOT/MUON/MUONTimeRawStreamTracker.C+
  98  MUONTimeRawStreamTracker(filename, maxEvent);
  99 </pre>
 100
 101 where \em filename is the name of a file containing the raw data, or alternatively
 102 the directory containing rawX (X being an integer) paths with the raw DDL
 103 data. The \em maxEvent value is the maximum event to process (default set to
 104 1000). Thus the macro will time the algorithm for all events in the range
 105 [0 .. maxEvent-1].
 106
 107
 108 \section raw_s3 Special flags for high performance tracker DDL decoder.
 109
 110 There are three flags that are available through the AliMUONRawStreamTrackerHP
 111 interface, which effect the decoding of raw data in special ways.
 112 \li TryRecover
 113 \li AutoDetectTrailer
 114 \li CheckForTrailer
 115
 116 The TryRecover flag is used to enable special logic in the decoder that tries
 117 to recover from a partially corrupt raw data structure header, or a corrupt/missing
 118 end of DDL trailer. Normally if the header is found to be corrupt (by seeing
 119 that the block lengths do not correspond),
 120 then the whole corresponding structure is skipped and we move on to the
 121 next structure that we are sure of, or skip the rest of the DDL.
 122 With the option to recover turned on, we attempt to figure out what the correct
 123 values for the structure length should have been. This is possible because there
 124 is redundant information in the headers giving the structure size. This recovery
 125 procedure will work for single bit flips found inside the headers, but obviously
 126 with more severe corruption, the header will not be recoverable.
 127 The TryRecover flag is set to kFALSE by default to disable this feature, meaning
 128 any structures in the raw data that cause problems in any way are skipped by
 129 default. More details about the corrupt header recovery procedure can be found
 130 in the method documentation AliMUONTrackerDDLDecoder::TryRecoverStruct().
 131
 132 The AutoDetectTrailer and CheckForTrailer flags are used to deal with the
 133 difference in raw data format from the real tracker chambers and the simulated
 134 data generated with AliRoot up to March 2008. The end of DDL trailer words are
 135 missing in the simulated raw data in the older versions of AliRoot. To tell the
 136 decoder that it should expect the trailer words as generated by the real readout
 137 electronics then the CheckForTrailer flag should be set to kTRUE (this is the
 138 default). If the trailer words are missing in the raw data then CheckForTrailer
 139 should be kFALSE. Alternatively one can set the flag AutoDetectTrailer to kTRUE
 140 (which is the default) so that the decoder will try to autodetect if the trailer
 141 words are there or not. When AutoDetectTrailer is set to kTRUE then the
 142 CheckForTrailer flag is ignored. Only when AutoDetectTrailer is set to kFALSE
 143 will the CheckForTrailer flag have an effect.
 144
 145 Each of these decoder flags can be set to kTRUE or kFALSE, or tested by the
 146 corresponding setter and getter methods respectively. For example, to set the
 147 TryRecover flag to kTRUE and fetch its value afterwards, use the following code:
 148 \code
 149 AliMUONRawStreamTrackerHP decoder;
 150 // to set the flag:
 151 decoder.TryRecover(kTRUE);
 152 // or to get the value of the flag:
 153 Bool_t value = decoder.TryRecover();
 154 \endcode
 155 Similarly, the other flags are manipulated with corresponding methods having
 156 the same name as the flag.
 157
 158
 159 This chapter is defined in the READMEraw.txt file.
 160
 161 */
 162