HLT/MUON/AliHLTMUONUtils.h

   1 #ifndef ALIHLTMUONUTILS_H
   2 #define ALIHLTMUONUTILS_H
   3 /* Copyright(c) 1998-2007, ALICE Experiment at CERN, All rights reserved. *
   4  * See cxx source for full Copyright notice                               */
   5
   6 /* $Id$ */
   7
   8 ///
   9 /// @file   AliHLTMUONUtils.h
  10 /// @author Artur Szostak <artursz@iafrica.com>
  11 /// @date
  12 /// @brief  Class containing various dimuon HLT utility routines and macros.
  13 ///
  14
  15 #include "AliHLTMUONDataTypes.h"
  16
  17 // Forward declare structures.
  18 extern "C" {
  19 struct AliHLTMUONTriggerRecordStruct;
  20 struct AliHLTMUONTriggerRecordsBlockStruct;
  21 struct AliHLTMUONTrigRecsDebugBlockStruct;
  22 struct AliHLTMUONTriggerChannelsBlockStruct;
  23 struct AliHLTMUONRecHitsBlockStruct;
  24 struct AliHLTMUONClustersBlockStruct;
  25 struct AliHLTMUONChannelsBlockStruct;
  26 struct AliHLTMUONMansoTrackStruct;
  27 struct AliHLTMUONMansoTracksBlockStruct;
  28 struct AliHLTMUONMansoCandidatesBlockStruct;
  29 struct AliHLTMUONTrackDecisionStruct;
  30 struct AliHLTMUONSinglesDecisionBlockStruct;
  31 struct AliHLTMUONPairDecisionStruct;
  32 struct AliHLTMUONPairsDecisionBlockStruct;
  33 } // extern "C"
  34
  35 /**
  36  * AliHLTMUONUtils contains arbitrary utility methods to be used in various
  37  * parts of the dimuon HLT system.
  38  * These include methods to perform basic sanity checks on the integrity of
  39  * data blocks.
  40  */
  41 class AliHLTMUONUtils
  42 {
  43 public:
  44         /**
  45          * This packs the given parameters into the bits of a word appropriate
  46          * for AliHLTMUONTriggerRecordStruct::fFlags.
  47          * @param sign    The particle sign.
  48          * @param hitset  Flags to indicate if the corresponding fHits[i] elements
  49          *                was set/filled.
  50          * @return  Returns the 32 bit packed word.
  51          */
  52         static AliHLTUInt32_t PackTriggerRecordFlags(
  53                         AliHLTMUONParticleSign sign, const bool hitset[4]
  54                 );
  55
  56         /**
  57          * This unpacks the AliHLTMUONTriggerRecordStruct::fFlags bits into
  58          * its component fields.
  59          * @param flags  The flags from an AliHLTMUONTriggerRecordStruct structure.
  60          * @param sign    Sets this to the particle sign.
  61          * @param hitset  Sets the array elements to indicate if the corresponding
  62          *                fHits[i] element was set/filled.
  63          */
  64         static void UnpackTriggerRecordFlags(
  65                         AliHLTUInt32_t flags, // [in]
  66                         AliHLTMUONParticleSign& sign, // [out]
  67                         bool hitset[4] // [out]
  68                 );
  69
  70         /**
  71          * This packs the given parameters into the bits of a word appropriate
  72          * for AliHLTMUONMansoTrackStruct::fFlags.
  73          * @param sign    The particle sign.
  74          * @param hitset  Flags to indicate if the corresponding fHits[i] elements
  75          *                was set/filled.
  76          * @return  Returns the 32 bit packed word.
  77          */
  78         static AliHLTUInt32_t PackMansoTrackFlags(
  79                         AliHLTMUONParticleSign sign, const bool hitset[4]
  80                 )
  81         {
  82                 return PackTriggerRecordFlags(sign, hitset);
  83         }
  84
  85         /**
  86          * This unpacks the AliHLTMUONMansoTrackStruct::fFlags bits into
  87          * its component fields.
  88          * @param flags  The flags from an AliHLTMUONMansoTrackStruct structure.
  89          * @param sign    Sets this to the particle sign.
  90          * @param hitset  Sets the array elements to indicate if the corresponding
  91          *                fHits[i] element was set/filled.
  92          */
  93         static void UnpackMansoTrackFlags(
  94                         AliHLTUInt32_t flags, // [in]
  95                         AliHLTMUONParticleSign& sign, // [out]
  96                         bool hitset[4] // [out]
  97                 )
  98         {
  99                 UnpackTriggerRecordFlags(flags, sign, hitset);
 100         }
 101
 102         /**
 103          * This packs the given parameters into the bits of a word appropriate
 104          * for AliHLTMUONTrackDecisionStruct::fTriggerBits.
 105          * @param highPt  Has the track passed the high pt cut.
 106          * @param lowPt   Has the track passed the low pt cut.
 107          * @return  Returns the 32 bit packed word.
 108          */
 109         static AliHLTUInt32_t PackTrackDecisionBits(bool highPt, bool lowPt);
 110
 111         /**
 112          * This unpacks the AliHLTMUONTrackDecisionStruct::fTriggerBits bits into
 113          * its component fields.
 114          * @param bits  The trigger bits from an AliHLTMUONTrackDecisionStruct
 115          *              structure.
 116          * @param highPt Sets this to the value of the high pt cut bit.
 117          * @param lowPt  Sets this to the value of the low pt cut bit.
 118          */
 119         static void UnpackTrackDecisionBits(
 120                         AliHLTUInt32_t bits, // [in]
 121                         bool& highPt, // [out]
 122                         bool& lowPt // [out]
 123                 );
 124
 125         /**
 126          * This packs the given parameters into the bits of a word appropriate
 127          * for AliHLTMUONPairDecisionStruct::fTriggerBits.
 128          *
 129          * @param highMass Has the track pair passed the high invariant mass cut.
 130          * @param lowMass  Has the track pair passed the low invariant mass cut.
 131          * @param unlike   Does the track pair have unlike signs.
 132          * @param highPtCount The number of tracks that passed the high pt cut
 133          *                    in the pair.
 134          * @param lowPtCount  The number of tracks that passed the low pt cut
 135          *                    in the pair.
 136          * @return  Returns the 32 bit packed word.
 137          *
 138          * Note: Must have highPtCount + lowPtCount <= 2 and unlike == true if
 139          * highMass or lowMass is true.
 140          */
 141         static AliHLTUInt32_t PackPairDecisionBits(
 142                         bool highMass, bool lowMass, bool unlike,
 143                         AliHLTUInt8_t highPtCount, AliHLTUInt8_t lowPtCount
 144                 );
 145
 146         /**
 147          * This unpacks the AliHLTMUONPairDecisionStruct::fTriggerBits bits into
 148          * its component fields.
 149          * @param bits  The trigger bits from an AliHLTMUONPairDecisionStruct
 150          *              structure.
 151          * @param highMass Sets this to the value of the high invariant mass cut bit.
 152          * @param lowMass  Sets this to the value of the low invariant mass cut bit.
 153          * @param unlike   Sets this if the pair is unlike sign.
 154          * @param highPtCount Sets this to the high pt count bits.
 155          * @param lowPtCount  Sets this to the low pt count bits.
 156          */
 157         static void UnpackPairDecisionBits(
 158                         AliHLTUInt32_t bits, // [in]
 159                         bool& highMass, // [out]
 160                         bool& lowMass, // [out]
 161                         bool& unlike, // [out]
 162                         AliHLTUInt8_t& highPtCount, // [out]
 163                         AliHLTUInt8_t& lowPtCount // [out]
 164                 );
 165
 166         /**
 167          * This packs the given parameters into the 32bit Pub/Sub specification
 168          * word in the data block descriptor.
 169          *
 170          * @param ddl  The list of DDLs forming part of the readout. ddl[0]
 171          *             indicates DDL number 2560, ddl[1] is for DDL 2561 and so
 172          *             on up to ddl[19]. ddl[20] and ddl[21] will be for the
 173          *             trigger DDLs 2816 and 2817 respectively.
 174          * @return  Returns the 32 bit packed specification word.
 175          */
 176         static AliHLTUInt32_t PackSpecBits(
 177                         const bool ddl[22]
 178                 );
 179
 180         /**
 181          * This unpacks the AliHLTMUONPairDecisionStruct::fTriggerBits bits into
 182          * its component fields.
 183          * @param bits  The Pub/Sub specification word from a data block descriptor.
 184          * @param ddl  The output list of DDLs forming part of the readout. ddl[0]
 185          *             indicates DDL number 2560, ddl[1] is for DDL 2561 and so
 186          *             on up to ddl[19]. ddl[20] and ddl[21] will be for the
 187          *             trigger DDLs 2816 and 2817 respectively.
 188          */
 189         static void UnpackSpecBits(
 190                         AliHLTUInt32_t bits, // [in]
 191                         bool ddl[22] // [out]
 192                 );
 193
 194         /**
 195          * This method converts the DDL number for the muon spectrometer in the
 196          * range [0..21] to the equipment ID number.
 197          * @param ddlNo  The DDL number in the range [0..21].
 198          * @return  Returns the equipment ID number or -1 if ddlNo was invalid.
 199          */
 200         static AliHLTInt32_t DDLNumberToEquipId(AliHLTInt32_t ddlNo);
 201
 202         /**
 203          * This method converts the equipment ID number for a muon spectrometer
 204          * DDL to the DDL number in the range [0..21].
 205          * @param id  The equipment ID of the DDL.
 206          * @return  Returns the DDL number in the range [0..21] or -1 if the
 207          *          equipment ID was invalid.
 208          */
 209         static AliHLTInt32_t EquipIdToDDLNumber(AliHLTInt32_t id);
 210
 211         /**
 212          * This method converts a 32 bit data block specification for a MUON-HLT
 213          * data block into its corresponding DDL equipment ID number.
 214          * It is assumed that the specification is for a data block comming from
 215          * a single DDL source. If more than one DDL contributed to the data block
 216          * then -1 is returned.
 217          * @param spec  The 32 bit specification for a data block.
 218          * @return  Returns the equipment ID corresponding to the specification
 219          *          or -1 if the specification was invalid.
 220          */
 221         static AliHLTInt32_t SpecToEquipId(AliHLTUInt32_t spec);
 222
 223         /**
 224          * This method converts a equipment ID number for a DDL into its corresponding
 225          * 32 bit data block specification for the MUON-HLT.
 226          * @param id  The equipment ID number of the DDL.
 227          * @return  Returns the 32 bit data block specification or 0x0 if the
 228          *          equipment ID was invalid.
 229          */
 230         static AliHLTUInt32_t EquipIdToSpec(AliHLTInt32_t id);
 231
 232         /**
 233          * This method converts a 32 bit data block specification for a MUON-HLT
 234          * data block into its corresponding DDL number in the range [0..21].
 235          * It is assumed that the specification is for a data block comming from
 236          * a single DDL source. If more than one DDL contributed to the data block
 237          * then -1 is returned.
 238          * @param spec  The 32 bit specification for a data block.
 239          * @return  Returns the corresponding DDL number for the specification
 240          *          or -1 if the specification was invalid.
 241          */
 242         static AliHLTInt32_t SpecToDDLNumber(AliHLTUInt32_t spec);
 243
 244         /**
 245          * This method converts a DDL number in the range [0..21] into its
 246          * corresponding 32 bit data block specification for the MUON-HLT.
 247          * @param ddlNo  The equipment ID number of the DDL.
 248          * @return  Returns the 32 bit data block specification or 0x0 if the
 249          *          DDL number was invalid (out of range).
 250          */
 251         static AliHLTUInt32_t DDLNumberToSpec(AliHLTInt32_t ddlNo);
 252
 253         /**
 254          * Returns true if the given specification was for a single trigger DDL.
 255          */
 256         static bool IsTriggerDDL(AliHLTUInt32_t spec)
 257         {
 258                 AliHLTInt32_t ddl = SpecToDDLNumber(spec);
 259                 return (20 <= ddl and ddl <= 21);
 260         }
 261
 262         /**
 263          * Returns true if the given specification was for a single tracker DDL.
 264          */
 265         static bool IsTrackerDDL(AliHLTUInt32_t spec)
 266         {
 267                 AliHLTInt32_t ddl = SpecToDDLNumber(spec);
 268                 return (0 <= ddl and ddl <= 19);
 269         }
 270
 271         /**
 272         * Parses the string containing the type name of a dHLT data block and
 273         * returns the corresponding AliHLTMUONDataBlockType value.
 274         * \param  type  The string containing the type name.
 275         * \returns  The data block type or kUnknownDataBlock if the type name
 276         *      is invalid.
 277         */
 278         static AliHLTMUONDataBlockType ParseCommandLineTypeString(const char* type);
 279
 280         /**
 281          * These codes indicate the reason why a data block failed its
 282          * validity check.
 283          */
 284         enum WhyNotValid
 285         {
 286                 kNoReason,
 287                 kHeaderContainsWrongType,
 288                 kHeaderContainsWrongRecordWidth
 289         };
 290
 291         /**
 292          * Methods used to check if the header information corresponds to the
 293          * supposed type of the data block.
 294          * If the 'reason' parameter is not NULL then these methods will fill the
 295          * memory pointed to by reason with a code describing of why the header
 296          * is not valid, if and only if a problem is found with the data.
 297          */
 298         static bool HeaderOk(const AliHLTMUONTriggerRecordsBlockStruct& block, WhyNotValid* reason = NULL);
 299         static bool HeaderOk(const AliHLTMUONTrigRecsDebugBlockStruct& block);
 300         static bool HeaderOk(const AliHLTMUONTriggerChannelsBlockStruct& block);
 301         static bool HeaderOk(const AliHLTMUONRecHitsBlockStruct& block);
 302         static bool HeaderOk(const AliHLTMUONClustersBlockStruct& block);
 303         static bool HeaderOk(const AliHLTMUONChannelsBlockStruct& block);
 304         static bool HeaderOk(const AliHLTMUONMansoTracksBlockStruct& block);
 305         static bool HeaderOk(const AliHLTMUONMansoCandidatesBlockStruct& block);
 306         static bool HeaderOk(const AliHLTMUONSinglesDecisionBlockStruct& block);
 307         static bool HeaderOk(const AliHLTMUONPairsDecisionBlockStruct& block);
 308
 309         /**
 310          * Methods used to check more extensively if the integrity of various
 311          * types of data blocks are Ok and returns true in that case.
 312          * These can be slow and should generally only be used for debugging.
 313          */
 314         static bool IntegrityOk(const AliHLTMUONTriggerRecordStruct& tr);
 315         static bool IntegrityOk(const AliHLTMUONTriggerRecordsBlockStruct& block);
 316         static bool IntegrityOk(const AliHLTMUONTrigRecsDebugBlockStruct& block);
 317         static bool IntegrityOk(const AliHLTMUONTriggerChannelsBlockStruct& block);
 318         static bool IntegrityOk(const AliHLTMUONRecHitsBlockStruct& block);
 319         static bool IntegrityOk(const AliHLTMUONClustersBlockStruct& block);
 320         static bool IntegrityOk(const AliHLTMUONChannelsBlockStruct& block);
 321         static bool IntegrityOk(const AliHLTMUONMansoTrackStruct& track);
 322         static bool IntegrityOk(const AliHLTMUONMansoTracksBlockStruct& block);
 323         static bool IntegrityOk(const AliHLTMUONMansoCandidatesBlockStruct& block);
 324         static bool IntegrityOk(const AliHLTMUONTrackDecisionStruct& decision);
 325         static bool IntegrityOk(const AliHLTMUONSinglesDecisionBlockStruct& block);
 326         static bool IntegrityOk(const AliHLTMUONPairDecisionStruct& decision);
 327         static bool IntegrityOk(const AliHLTMUONPairsDecisionBlockStruct& block);
 328
 329 private:
 330         // Should never have to create or destroy this object.
 331         AliHLTMUONUtils();
 332         ~AliHLTMUONUtils();
 333 };
 334
 335 //_____________________________________________________________________________
 336
 337 // Since c++ is missing a finally "keyword" we define one. Its usage is identical
 338 // to a try..finally statement in Java etc.. however, since it is officialy a macro
 339 // one must use the ( ) brackets instead of { }
 340 // If the compiler supports __finally use it otherwise make our own.
 341 #if defined(__BORLANDC__)
 342 #       define finally(str) __finally{str}
 343 #else
 344 #       define finally(code) \
 345                 catch(...) \
 346                 { \
 347                         code \
 348                         throw; \
 349                 }; \
 350                 code
 351 #endif // __BORLANDC__
 352
 353 // If we do not already have them, then define logical operators that are easier
 354 // to read. 'and' = &&, 'or' = ||, 'not' = !
 355 #if ! defined(__GNUC__) && ! defined(__CINT__)
 356 // TODO: Should use iso646.h
 357 #       define and &&
 358 #       define or ||
 359 #       define not !
 360 #endif // __GNUC__ | __CINT__
 361
 362
 363 // Here we define the DebugTrace(message) macro for easy embedding of debug
 364 // information into the dimuon HLT code. Its usage is meant to be for generating
 365 // traces of the program which are only useful during full scale debugging.
 366 // Log messages should use the standard HLT logging mechanisms.
 367 // The output is only generated in programs compiled with the DEBUG directive
 368 // defined. Here is a usage example:
 369 //
 370 //  // statements...
 371 //  DebugTrace("some debug information.");
 372 //  // statements...
 373 //
 374 // One can also use C++ ostream operators and manipulators like so:
 375 //
 376 //  // statements...
 377 //  int x, y;
 378 //  DebugTrace("x = " << x << " and y = 0x" << std::hex << y );
 379 //  // statements...
 380 //
 381 #ifdef DEBUG
 382 #       include <iostream>
 383 #       define DebugTrace(message) {std::cout << message << std::endl;}
 384 #else // DEBUG
 385 #       define DebugTrace(message)
 386 #endif // DEBUG
 387
 388
 389 #endif // ALIHLTMUONUTILS_H