doing backward compatibility correctly
[u/mrichter/AliRoot.git] / HLT / rec / AliHLTReconstructor.h
index 44562289bb0d2528b94dee79d7580112521e02b3..cd808c1df1536ea45490fd5bb4013dd53414e4f1 100644 (file)
@@ -2,40 +2,41 @@
 
 #ifndef ALIHLTRECONSTRUCTOR_H
 #define ALIHLTRECONSTRUCTOR_H
-/* This file is property of and copyright by the ALICE HLT Project        * 
- * ALICE Experiment at CERN, All rights reserved.                         *
- * See cxx source for full Copyright notice                               */
+//* This file is property of and copyright by the ALICE HLT Project        * 
+//* ALICE Experiment at CERN, All rights reserved.                         *
+//* See cxx source for full Copyright notice                               *
 
-/** @file   AliHLTSimulation.h
+/** @file   AliHLTReconstructor.h
     @author Matthias Richter
     @date   
     @brief  Binding class for HLT simulation in AliRoot
-
-// see below for class documentation
-// or
-// refer to README to build package
-// or
-// visit http://web.ift.uib.no/~kjeks/doc/alice-hlt
-                                                                          */
+*/
 
 #include "AliReconstructor.h"
+#include "AliHLTReconstructorBase.h"
 
 class AliHLTSystem;
 class AliRawReader;
 class AliESDEvent;
+class AliHLTOUT;
+class AliHLTEsdManager;
 
 /**
  * @class AliHLTReconstructor
- * AliHLTReconstructor AliRoot event reconstruction plugin for the HLT.
+ * AliHLTReconstructor AliRoot event reconstruction plug-in for the HLT.
  * The AliHLTReconstructor holds an instance of the @ref AliHLTSystem
  * steering class. The actual reconstruction depends on the loaded component
  * libraries. Each library must implement a module agent (@ref AliHLTModuleAgent)
  * in order to provide information on the supported features and the
  * configurations to be run.
  *
+ * The AliHLTReconstructor provides both the functionality to run customized
+ * analysis chains and the treatment of the HLTOUT data.
+ *
+ * @section sec_alihltreconstructor_options Options
  * The default component libraries which are loaded through the initialization
- * are determined by the @ref kHLTDefaultLibs array. The library loading can
- * be overridden by an option to the AliHLTReconstructor through the
+ * are determined by the @ref AliHLTSystem::fgkHLTDefaultLibs array. The library
+ * loading can be overridden by an option to the AliHLTReconstructor through the
  * <tt>SetOption</tt> method of <tt>AliReconstruction</tt>, e.g.
  * <pre>
  * AliReconstruction rec;
@@ -44,7 +45,7 @@ class AliESDEvent;
  * will only load <tt>libAliHLTSample.so</tt>
  * 
  * Optional arguments:<br>
- * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formating -->
+ * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formatting -->
  * \li loglevel=<i>level</i><br>
  *     level can be a hex number encoding the @ref AliHLTComponentLogSeverity
  * \li alilog=off <br>
@@ -52,16 +53,99 @@ class AliESDEvent;
  *
  * For further information on the AliRoot reconstruction refer to the AliRoot
  * documentation, namely <tt>AliReconstruction</tt>.
+ *
+ * @section sec_alihltreconstructor_chains Custom reconstruction chains
+ * In order to run an HLT chain during the AliRoot reconstruction, a chain
+ * configuration must be defined. This can be done by
+ * - specifying a configuration macro defining a configuration macro and
+ *   the name of the chain as parameters
+ *   <pre>
+ *   rec.SetOption("HLT", "config=[macro.C] chains=[name]")
+ *   </pre>
+ * - providing the configuration and the name by the module agent.
+ *   AliHLTModuleAgent and the functions AliHLTModuleAgent::CreateConfigurations
+ *   and AliHLTModuleAgent::GetReconstructionChains
+ *
+ * @section sec_alihltreconstructor_hltout Treatment of HLTOUT data.
+ * The HLTOUT data is a collation of output blocks produced by the various
+ * components running in an HLT chain. Typically its the output of the last
+ * component(s) in the chain, or components specifically connected to the HLT
+ * output.
+ *
+ * The treatment of the HLTOUT data blocks is implemented in handlers of type
+ * AliHLTOUTHandler. The AliHLTModuleAgent of the module  creates the appropriate
+ * handler for a data block.
+ * The data type of the individual blocks is set by the producer component and
+ * specifies the nature of the data processing. There are 5 overall groups:
+ * - output is in ESD format:
+ *      @ref sec_alihltreconstructor_hltout_esd
+ * - data describes DDL raw format:
+ *      @ref sec_alihltreconstructor_hltout_rawreader
+ * - pre-analyzed data to be fed into the normal reconstruction:
+ *      @ref sec_alihltreconstructor_hltout_rawstream
+ * - data is fed into an analysis chain:
+ *      @ref sec_alihltreconstructor_hltout_chain
+ * - detector specific handler:
+ *      @ref sec_alihltreconstructor_hltout_proprietary
+ *
+ * @subsection sec_alihltreconstructor_hltout_esd ESD HLTOUT data
+ * The frame work implements a standard handling of
+ * ESD data blocks of type ::kAliHLTDataTypeESDTree {ESD_TREE:ANY}. ANY can be
+ * any detector origin. Each ESD block contains the data of only one event,
+ * the ESDs are merged by the AliHLTEsdManager and written to files of the
+ * naming scheme AliHLT<DET>ESDs.root. The first ESD block is also copied
+ * to the hltEsd provided by the AliReconstruction. This is a temporary
+ * solution as the handling and merging of HLT ESDs is under discussion.
+ * At the time of writing (May 08) only the TPC HLT components produce ESD
+ * blocks.
+ * The module agent can provide a handler for multiple ESD data blocks, e.g.
+ * for merging within one event prior to the writing. Instead of the individual
+ * ESDs the one provided by the handler is passed to the AliHLTEsdManager. The
+ * handler is of type AliHLTModuleAgent::AliHLTOUTHandlerType::kEsd
+ *
+ * @subsection sec_alihltreconstructor_hltout_rawreader DDL raw HLTOUT data
+ * The HLT can perform selective readout and produces a reduced amount of data
+ * in the original raw ddl format. In order to feed this data from the HLTOUT
+ * DDL links into the normal reconstruction, a handler of type 
+ * @ref AliHLTModuleAgent::AliHLTOUTHandlerType::kRawReader must be implemented and provided by the
+ * module agent. The handler has to derive the original equipment id from the
+ * data type and specification of the block. The offline reconstruction does
+ * not need to be changed or adapted at all.
+ *
+ * @subsection sec_alihltreconstructor_hltout_rawstream Preprocessed Raw HLTOUT data
+ * Handlers type @ref AliHLTModuleAgent::AliHLTOUTHandlerType::kRawStream are foreseen though at the time of writing (May 08) the
+ * concept is not fixed. Advanced data compression algorithms can produce a
+ * raw data format which is not convertible into the raw DDL data, e.g. lossy
+ * compression techniques storing clusters parametrized regarding to tracks. A
+ * specific RawStream is needed here since the data is detector specific and the
+ * first stage of the offline reconstruction might need some adaptions.
+ *
+ * @subsection sec_alihltreconstructor_hltout_chain HLTOUT data fed into a chain
+ * At the time of writing (May 08), handler type @ref AliHLTModuleAgent::AliHLTOUTHandlerType::kChain
+ * is foreseen but not yet implemented. Has to be discussed.
+ *
+ * @subsection sec_alihltreconstructor_hltout_proprietary Proprietary HLTOUT data
+ * This is a handler of proprietary detector data, @ref AliHLTModuleAgent::AliHLTOUTHandlerType::kProprietary.
+ * Handlers of this type do not have any standard output to the framework. Data
+ * can be processed and stored to files.
+ *
+ * @ingroup alihlt_aliroot_reconstruction
  */
-class AliHLTReconstructor: public AliReconstructor {
+class AliHLTReconstructor: public AliReconstructor, public AliHLTReconstructorBase {
 public:
+  /** standard constructor */
   AliHLTReconstructor();
+  /** constructor */
+  AliHLTReconstructor(const char* options);
   /** destructor */
   virtual ~AliHLTReconstructor();
 
   /** init the reconstructor */
   void Init();
 
+  /** init the reconstructor */
+  void Init(const char* options);
+
   /**
    * This Reconstructor function is not applicable for the AliHLTReconstructor
    * as it gets a detector specific digits tree. But HLT processes all detectors.
@@ -69,6 +153,9 @@ public:
    * The function forwards to the default bahavior of AliReconstructor but gives
    * a warning if there were options set, i.e. the user runs customized
    * reconstruction.
+   *
+   * @note HLT reconstruction on simulated data is processed at the end of
+   * simulation. <br>
    */
   void Reconstruct(TTree* digitsTree, TTree* clustersTree) const;
 
@@ -80,31 +167,70 @@ public:
   void Reconstruct(AliRawReader* rawReader, TTree* clustersTree) const;
 
   /**
-   * This function is purely for simulated data and not applicable for HLT.
-   * HLT reconstruction on simulated data is processed at the end of
-   * simulation. <br>
-   * The function forwards to the default bahavior of AliReconstructor but gives
-   * a warning if there were options set, i.e. the user runs customized
-   * reconstruction.
+   * This function treats the simulated HLTOUT data.
+   * Opens a handler for simulated HLTOUT data and forwards to ::ProcessHLTOUT.
    */
   void FillESD(TTree* digitsTree, TTree* clustersTree, AliESDEvent* esd) const;
 
   /**
-   * Fill the ESD from RAW data.
-   * This is the main entry for HLT reconstruction of RAW data. It performs both
-   * the analysis by the defined chains and the filling of the ESD.
+   * Process the raw HLTOUT data and fill ESD.
+   * Opens a handler for raw HLTOUT data and forwards to ::ProcessHLTOUT.
    */
   void FillESD(AliRawReader* rawReader, TTree* clustersTree, AliESDEvent* esd) const;
 
+  /**
+   * Process HLTOUT data and fill ESD.
+   * This is the final treatment of the HLTOUT data, either simulated or real.
+   * HLTOUT data is stored in HOMER format, the AliHLTOUT object provides the interface
+   * to the individual data blocks.
+   *
+   * During reconstruction (::Reconstruct), module or user defined chains can be
+   * processed and may add additional data to the HLTOUT object. This data is then
+   * treated in the same way.
+   */
+  void ProcessHLTOUT(AliHLTOUT* pHLTOUT, AliESDEvent* esd) const;
+
+  /**
+   * Process HLTOUT data.
+   * Open digit file and process the HLTOUT digit data.
+   * This function is mostly intended for debugging purposes and stand-alone
+   * processing of the output from the simulation. Loops over all events.
+   * @param digitFile        path of the digit file
+   * @param pEsd             optional ESD to be filled
+   */
+  void ProcessHLTOUT(const char* digitFile="HLT.Digits.root", AliESDEvent* pEsd=NULL) const;
+
+  /**
+   * Process HLTOUT data.
+   * Process the HLTOUT from the raw reader.
+   * This function is mostly intended for debugging purposes and stand-alone
+   * processing of simulated or real raw data. 
+   * \em Note: Loops over all events, i.e. the current event of the the raw
+   * reader will change. Not to be called inside the normal AliRoot processsing.
+   * @param pRawReader       raw reader instance
+   * @param pEsd             optional ESD to be filled
+   */
+  void ProcessHLTOUT(AliRawReader* pRawReader, AliESDEvent* pEsd=NULL) const;
+
+  /**
+   * Print a short info about the HLTOUT content.
+   */
+  void PrintHLTOUTContent(AliHLTOUT* pHLTOUT) const;
+
 private:
   /** copy constructor prohibited */
   AliHLTReconstructor(const AliHLTReconstructor& src);
   /** assignment operator prohibited */
   AliHLTReconstructor& operator=(const AliHLTReconstructor& src);
 
-  AliHLTSystem* fpSystem; //! HLT steering object
+  /** function pointer: processing of HLTOUT data */
+  void* fFctProcessHLTOUT; //!transient
+
+  /** ESD manger instance for this reconstruction */
+  AliHLTEsdManager* fpEsdManager; //!transient
+
+  ClassDef(AliHLTReconstructor, 5)   // class for the HLT reconstruction
 
-  ClassDef(AliHLTReconstructor, 3)   // class for the HLT reconstruction
 };
 
 typedef AliHLTReconstructor AliL3Reconstructor; // for backward compatibility