HLT/rec/AliHLTReconstructor.h

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