HLT/rec/AliHLTReconstructor.h

   1 //-*- Mode: C++ -*-
   2 // $Id$
   3
   4 #ifndef ALIHLTRECONSTRUCTOR_H
   5 #define ALIHLTRECONSTRUCTOR_H
   6 //* This file is property of and copyright by the ALICE HLT Project        *
   7 //* ALICE Experiment at CERN, All rights reserved.                         *
   8 //* See cxx source for full Copyright notice                               *
   9
  10 //  @file   AliHLTReconstructor.h
  11 //  @author Matthias Richter
  12 //  @date
  13 //  @brief  Binding class for HLT reconstruction in AliRoot
  14 //          Implements bot the interface to run HLT chains embedded into
  15 //          AliReconstruction and the unpacking and treatment of HLTOUT
  16
  17 #include "AliReconstructor.h"
  18
  19 class AliHLTSystem;
  20 class AliRawReader;
  21 class AliESDEvent;
  22 class AliHLTOUT;
  23 class AliHLTEsdManager;
  24 class AliHLTPluginBase;
  25 /**
  26  * @defgroup alihlt_aliroot_reconstruction AliRoot reconstruction.
  27  *
  28  * @section alihlt_aliroot_reconstruction_intro General Remarks
  29  * Like all other ALICE detectors, HLT utilizes the AliReconstruction interface
  30  * to implement a plugin for the AliRoot reconstruction. The reconstructor can be
  31  * used to
  32  * -# run HLT analysis chains in the AliRoot reconstruction <br>
  33  *    This option is mainly intended for the <em>development and debugging cycle</em>.
  34  *    HLT chains can be defined by means of AliHLTConfiguration and can be run either
  35  *    stand-alone or embedded into the AliReconstruction cycle.
  36  * -# run the default analysis chains <br>
  37  *    HLT modules can define default analysis chains to be run during AliRoot
  38  *    reconstruction.
  39  * -# handle the HLTOUT data<br>
  40  *    The HLT output stream contains multiple data blocks produced by the various
  41  *    components of the HLT chain. Each block might need different and even
  42  *    detector specific processing, like e.g. the processing of ESD objects or the
  43  *    handling of compressed data.
  44  *
  45  * @section alihlt_aliroot_reconstruction_steering Steering
  46  * The AliHLTReconstructor provides the main interface for the reconstruction.
  47  * The handling of the HLTOUT data is described in AliRawReaderHLT.
  48  *
  49  * @section alihlt_aliroot_reconstruction_examples Examples
  50  * @subsection alihlt_aliroot_reconstruction_examples_reco Run chains
  51  * - @ref tut_reconstruction
  52  *
  53  * @subsection alihlt_aliroot_reconstruction_examples_hltout Handle HLTOUT
  54  * - @ref tut_alirawreaderhlt
  55  *
  56  * @ingroup alihlt_system
  57  */
  58
  59 /**
  60  * @class AliHLTReconstructor
  61  * AliRoot event reconstruction plug-in for the HLT.
  62  * The AliHLTReconstructor holds an instance of the @ref AliHLTSystem
  63  * steering class. The actual reconstruction depends on the loaded component
  64  * libraries. Each library must implement a module agent (@ref AliHLTModuleAgent)
  65  * in order to provide information on the supported features and the
  66  * configurations to be run.
  67  *
  68  * The AliHLTReconstructor provides both the functionality to run customized
  69  * analysis chains and the treatment of the HLTOUT data.
  70  *
  71  * @section sec_alihltreconstructor_options Options
  72  * The default component libraries which are loaded through the initialization
  73  * are determined by the @ref AliHLTSystem::fgkHLTDefaultLibs array. The library
  74  * loading can be overridden by an option to the AliHLTReconstructor through the
  75  * <tt>SetOption</tt> method of <tt>AliReconstruction</tt>, e.g.
  76  * <pre>
  77  * AliReconstruction rec;
  78  * rec.SetOption("HLT", "libAliHLTSample.so");
  79  * </pre>
  80  * will only load <tt>libAliHLTSample.so</tt>
  81  *
  82  * Optional arguments:<br>
  83  * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formatting -->
  84  * \li loglevel=<i>level</i><br>
  85  *     level can be a hex number encoding the @ref AliHLTComponentLogSeverity
  86  * \li alilog=off <br>
  87  *     disables the logging of HLT log messages through <tt>AliLog</tt> <br>
  88  * \li ignore-hltout <br>
  89  *     ignore data from the HLTOUT data links
  90  * \li ignore-ctp <br>
  91  *     ignore CTP trigger setup
  92  * \li esdmanager=<option> <br>
  93  *     options passed to the AliHLTEsdManager
  94  *
  95  * For further information on the AliRoot reconstruction refer to the AliRoot
  96  * documentation, namely <tt>AliReconstruction</tt>.
  97  *
  98  * @section sec_alihltreconstructor_chains Custom reconstruction chains
  99  * In order to run an HLT chain during the AliRoot reconstruction, a chain
 100  * configuration must be defined. This can be done by
 101  * - specifying a configuration macro defining a configuration macro and
 102  *   the name of the chain as parameters
 103  *   <pre>
 104  *   rec.SetOption("HLT", "config=[macro.C] chains=[name]")
 105  *   </pre>
 106  * - providing the configuration and the name by the module agent.
 107  *   AliHLTModuleAgent and the functions AliHLTModuleAgent::CreateConfigurations
 108  *   and AliHLTModuleAgent::GetReconstructionChains
 109  *
 110  * @section sec_alihltreconstructor_hltout Treatment of HLTOUT data.
 111  * The HLTOUT data is a collation of output blocks produced by the various
 112  * components running in an HLT chain. Typically its the output of the last
 113  * component(s) in the chain, or components specifically connected to the HLT
 114  * output.
 115  *
 116  * The treatment of the HLTOUT data blocks is implemented in handlers of type
 117  * AliHLTOUTHandler. The AliHLTModuleAgent of the module  creates the appropriate
 118  * handler for a data block.
 119  * The data type of the individual blocks is set by the producer component and
 120  * specifies the nature of the data processing. There are 5 overall groups:
 121  * - output is in ESD format:
 122  *      @ref sec_alihltreconstructor_hltout_esd
 123  * - data describes DDL raw format:
 124  *      @ref sec_alihltreconstructor_hltout_rawreader
 125  * - pre-analyzed data to be fed into the normal reconstruction:
 126  *      @ref sec_alihltreconstructor_hltout_rawstream
 127  * - data is fed into an analysis chain:
 128  *      @ref sec_alihltreconstructor_hltout_chain
 129  * - detector specific handler:
 130  *      @ref sec_alihltreconstructor_hltout_proprietary
 131  *
 132  * @subsection sec_alihltreconstructor_hltout_esd ESD HLTOUT data
 133  * The framework implements a standard handling of ESD data
 134  * blocks of type ::kAliHLTDataTypeESDObject {ALIESDV0:ANY} and
 135  * ::kAliHLTDataTypeESDTree {ESD_TREE:ANY}. Please note that the V0 refers to
 136  * a foreseen version number, not the AliESDV0 class. \em ANY can be
 137  * any detector origin. Each ESD block contains the data of only one event,
 138  * the ESDs are merged by the AliHLTEsdManager into the hltEsd. Optionally,
 139  * ESD contributions are written to files following the naming scheme
 140  * AliHLT\em DET ESDs.root. This debugging feature can be enabled by option
 141  * esdmanager='-writelocal -directory=dir'. The specification of target
 142  * directory is optional.
 143  *
 144  * The module agent can provide a handler for multiple ESD data blocks, e.g.
 145  * for merging within one event prior to the writing. Instead of the individual
 146  * ESDs the one provided by the handler is passed to the AliHLTEsdManager. The
 147  * handler is of type \link AliHLTModuleAgent::AliHLTOUTHandlerType kEsd \endlink.
 148  *
 149  * A specific handler AliHLTOUTHandlerEsdBranch allows to simply merge a
 150  * streamed Root object into the ESD. The class can be used as-is by just
 151  * specifying the data type and specification of the relevant data block and
 152  * the branch name. Alternatively, a child class can implement conversion of
 153  * binary data to a Root object or merging of several data blocks into one
 154  * object to be added to the ESD. \b Note: in order to create the branch at
 155  * the beginning of reconstruction the hltEsd layout needs to be adjusted.
 156  *
 157  * @subsection sec_alihltreconstructor_hltout_rawreader DDL raw HLTOUT data
 158  * The HLT can perform selective readout and produces a reduced amount of data
 159  * in the original raw ddl format. In order to feed this data from the HLTOUT
 160  * DDL links into the normal reconstruction, a handler of type
 161  * \link AliHLTModuleAgent::AliHLTOUTHandlerType kRawReader \endlink must be
 162  * implemented and provided by the
 163  * module agent. The handler has to derive the original equipment id from the
 164  * data type and specification of the block. The offline reconstruction does
 165  * not need to be changed or adapted at all. See AliRawReaderHLT for details.
 166  *
 167  * @subsection sec_alihltreconstructor_hltout_rawstream Preprocessed Raw HLTOUT data
 168  * Handlers of type \link AliHLTModuleAgent::AliHLTOUTHandlerType kRawStream \endlink
 169  * are foreseen though at the time of writing (May 08) the
 170  * concept is not fixed. Advanced data compression algorithms can produce a
 171  * raw data format which is not convertible into the raw DDL data, e.g. lossy
 172  * compression techniques storing clusters parametrized regarding to tracks. A
 173  * specific RawStream is needed here since the data is detector specific and the
 174  * first stage of the offline reconstruction might need some adaptions.
 175  *
 176  * @subsection sec_alihltreconstructor_hltout_chain HLTOUT data fed into a chain
 177  * Handlers of type \link AliHLTModuleAgent::AliHLTOUTHandlerType kChain \endlink
 178  * can execute a normal HLT chain and thus process HLTOUT data blocks by normal
 179  * HLT components just as if the components were running on-line. The base class
 180  * is provided by AliHLTOUTHandlerChain and can be used as it is just specifying
 181  * the chain to be run.<br>
 182  * Example:
 183  *
 184  * @subsection sec_alihltreconstructor_hltout_proprietary Proprietary HLTOUT data
 185  * This is a handler of proprietary detector data. Handlers of type
 186  * \link AliHLTModuleAgent::AliHLTOUTHandlerType kProprietary \endlink
 187  * do not have any standard output to the framework. Data can be processed and
 188  * stored to files.
 189  *
 190  * @section sec_alihltreconstructor_helper Tools and helper functions
 191  * Some helper functions of the AliHLTReconstruction can be used in stand-alone
 192  * mode. Remember to Init() the reconstructor.
 193  * <pre>
 194  * {
 195  * gSystem->Load("libHLTrec.so");
 196  * AliHLTReconstructor rec;
 197  * rec.Init();
 198  * // do something
 199  * }
 200  * </pre>
 201  * @subsection sec_alihltreconstructor_hltout_standalone Stand-alone HLTOUT processing
 202  * - HLTOUT processing from a digit file:
 203  * <pre>
 204  *  void ProcessHLTOUT(const char*, AliESDEvent*) const;
 205  * </pre>
 206  * - HLTOUT processing from an AliRawReader
 207  * <pre>
 208  *  void ProcessHLTOUT(AliRawReader*, AliESDEvent*) const;
 209  * </pre>
 210  *
 211  * @ingroup alihlt_aliroot_reconstruction
 212  * @section sec_alihltreconstructor_members Class members
 213  */
 214 class AliHLTReconstructor: public AliReconstructor {
 215 public:
 216   /** standard constructor */
 217   AliHLTReconstructor();
 218   /** constructor */
 219   AliHLTReconstructor(const char* options);
 220   /** destructor */
 221   virtual ~AliHLTReconstructor();
 222
 223   /** init the reconstructor */
 224   void Init();
 225
 226   /** init the reconstructor */
 227   void Init(const char* options);
 228
 229   /**
 230    * Init streamer infos for the relevent classes to be extracted from HLT raw
 231    * data payload. Reads the info from HLT/Calib/StreamerInfo
 232    */
 233   int InitStreamerInfos();
 234
 235   /**
 236    * Init streamer infos for the relevant classes to be extracted from HLT raw
 237    * data payload.
 238    */
 239   int InitStreamerInfos(TObjArray* pSchemas) const;
 240
 241   /**
 242    * Build the CTP_TRIGGER_CLASSES string from CTP trigger configuration
 243    */
 244   int BuildCTPTriggerClassString(TString& triggerclasses) const;
 245
 246   /**
 247    * This Reconstructor function is not applicable for the AliHLTReconstructor
 248    * as it gets a detector specific digits tree. But HLT processes all detectors.
 249    * Furthermore it's purely simulated data. <br>
 250    * The function forwards to the default bahavior of AliReconstructor but gives
 251    * a warning if there were options set, i.e. the user runs customized
 252    * reconstruction.
 253    *
 254    * @note HLT reconstruction on simulated data is processed at the end of
 255    * simulation. <br>
 256    */
 257   void Reconstruct(TTree* digitsTree, TTree* clustersTree) const;
 258
 259   /**
 260    * Reconstruction from RAW data.
 261    * The rawReader holds data for all detectors and this version of Reconstruct
 262    * is thus applicable for the HLT. The clustersTree is just ignored.
 263    */
 264   void Reconstruct(AliRawReader* rawReader, TTree* clustersTree) const;
 265
 266   /**
 267    * This function treats the simulated HLTOUT data.
 268    * Opens a handler for simulated HLTOUT data and forwards to ::ProcessHLTOUT.
 269    */
 270   void FillESD(TTree* digitsTree, TTree* clustersTree, AliESDEvent* esd) const;
 271
 272   /**
 273    * Process the raw HLTOUT data and fill ESD.
 274    * Opens a handler for raw HLTOUT data and forwards to ::ProcessHLTOUT.
 275    */
 276   void FillESD(AliRawReader* rawReader, TTree* clustersTree, AliESDEvent* esd) const;
 277
 278   /**
 279    * Process HLTOUT data and fill ESD.
 280    * This is the final treatment of the HLTOUT data, either simulated or real.
 281    * HLTOUT data is stored in HOMER format, the AliHLTOUT object provides the interface
 282    * to the individual data blocks.
 283    *
 284    * During reconstruction (::Reconstruct), module or user defined chains can be
 285    * processed and may add additional data to the HLTOUT object. This data is then
 286    * treated in the same way.
 287    */
 288   void ProcessHLTOUT(AliHLTOUT* pHLTOUT, AliESDEvent* esd, bool bVerbose=false) const;
 289
 290   /**
 291    * Process HLTOUT data.
 292    * Open digit file and process the HLTOUT digit data.
 293    * This function is mostly intended for debugging purposes and stand-alone
 294    * processing of the output from the simulation. Loops over all events.
 295    * @param digitFile        path of the digit file
 296    * @param pEsd             optional ESD to be filled
 297    */
 298   void ProcessHLTOUT(const char* digitFile="HLT.Digits.root", AliESDEvent* pEsd=NULL) const;
 299
 300   /**
 301    * Process HLTOUT data.
 302    * Process the HLTOUT from the raw reader.
 303    * This function is mostly intended for debugging purposes and stand-alone
 304    * processing of simulated or real raw data.
 305    * \em Note: Loops over all events, i.e. the current event of the the raw
 306    * reader will change. Not to be called inside the normal AliRoot processsing.
 307    * @param pRawReader       raw reader instance
 308    * @param pEsd             optional ESD to be filled
 309    */
 310   void ProcessHLTOUT(AliRawReader* pRawReader, AliESDEvent* pEsd=NULL) const;
 311
 312   /**
 313    * Print a short info about the HLTOUT content.
 314    */
 315   void PrintHLTOUTContent(AliHLTOUT* pHLTOUT) const;
 316
 317   enum {
 318     /// ignore the blocks from the HLTOUT payload
 319     kAliHLTReconstructorIgnoreHLTOUT = 0x1,
 320     kAliHLTReconstructorIgnoreCTP = 0x2,
 321     kAliHLTReconstructorLastFlag
 322   };
 323
 324 private:
 325   /** copy constructor prohibited */
 326   AliHLTReconstructor(const AliHLTReconstructor& src);
 327   /** assignment operator prohibited */
 328   AliHLTReconstructor& operator=(const AliHLTReconstructor& src);
 329
 330   /** ESD manger instance for this reconstruction */
 331   AliHLTEsdManager* fpEsdManager; //!transient
 332
 333   /** base class for AliRoot HLT plugins */
 334   AliHLTPluginBase* fpPluginBase;                                     //!transient
 335
 336   UInt_t fFlags; //! transient
 337
 338   static const char* fgkCalibStreamerInfoEntry; //! OCDB path
 339
 340   ClassDef(AliHLTReconstructor, 8)   // class for the HLT reconstruction
 341
 342 };
 343
 344 typedef AliHLTReconstructor AliL3Reconstructor; // for backward compatibility
 345
 346 #endif