4db5e6a740837284d5dd558dffd5932fb9ed5f6a
[u/mrichter/AliRoot.git] / 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  * \li ignore-hltout <br>
87  *     ignore data from the HLTOUT data links
88  * \li ignore-ctp <br>
89  *     ignore CTP trigger setup
90  * \li esdmanager=<option> <br>
91  *     options passed to the AliHLTEsdManager
92  *
93  * For further information on the AliRoot reconstruction refer to the AliRoot
94  * documentation, namely <tt>AliReconstruction</tt>.
95  *
96  * @section sec_alihltreconstructor_chains Custom reconstruction chains
97  * In order to run an HLT chain during the AliRoot reconstruction, a chain
98  * configuration must be defined. This can be done by
99  * - specifying a configuration macro defining a configuration macro and
100  *   the name of the chain as parameters
101  *   <pre>
102  *   rec.SetOption("HLT", "config=[macro.C] chains=[name]")
103  *   </pre>
104  * - providing the configuration and the name by the module agent.
105  *   AliHLTModuleAgent and the functions AliHLTModuleAgent::CreateConfigurations
106  *   and AliHLTModuleAgent::GetReconstructionChains
107  *
108  * @section sec_alihltreconstructor_hltout Treatment of HLTOUT data.
109  * The HLTOUT data is a collation of output blocks produced by the various
110  * components running in an HLT chain. Typically its the output of the last
111  * component(s) in the chain, or components specifically connected to the HLT
112  * output.
113  *
114  * The treatment of the HLTOUT data blocks is implemented in handlers of type
115  * AliHLTOUTHandler. The AliHLTModuleAgent of the module  creates the appropriate
116  * handler for a data block.
117  * The data type of the individual blocks is set by the producer component and
118  * specifies the nature of the data processing. There are 5 overall groups:
119  * - output is in ESD format:
120  *      @ref sec_alihltreconstructor_hltout_esd
121  * - data describes DDL raw format:
122  *      @ref sec_alihltreconstructor_hltout_rawreader
123  * - pre-analyzed data to be fed into the normal reconstruction:
124  *      @ref sec_alihltreconstructor_hltout_rawstream
125  * - data is fed into an analysis chain:
126  *      @ref sec_alihltreconstructor_hltout_chain
127  * - detector specific handler:
128  *      @ref sec_alihltreconstructor_hltout_proprietary
129  *
130  * @subsection sec_alihltreconstructor_hltout_esd ESD HLTOUT data
131  * The framework implements a standard handling of ESD data
132  * blocks of type ::kAliHLTDataTypeESDTree {ESD_TREE:ANY}. \em ANY can be
133  * any detector origin. Each ESD block contains the data of only one event,
134  * the ESDs are merged by the AliHLTEsdManager and written to files of the
135  * naming scheme AliHLT\em DET ESDs.root. The first ESD block is also copied
136  * to the hltEsd provided by the AliReconstruction. This is a temporary
137  * solution as the handling and merging of HLT ESDs is under discussion.
138  * At the time of writing (May 08) only the TPC HLT components produce ESD
139  * blocks.
140  * The module agent can provide a handler for multiple ESD data blocks, e.g.
141  * for merging within one event prior to the writing. Instead of the individual
142  * ESDs the one provided by the handler is passed to the AliHLTEsdManager. The
143  * handler is of type \link AliHLTModuleAgent::AliHLTOUTHandlerType kEsd \endlink.
144  *
145  * @subsection sec_alihltreconstructor_hltout_rawreader DDL raw HLTOUT data
146  * The HLT can perform selective readout and produces a reduced amount of data
147  * in the original raw ddl format. In order to feed this data from the HLTOUT
148  * DDL links into the normal reconstruction, a handler of type 
149  * \link AliHLTModuleAgent::AliHLTOUTHandlerType kRawReader \endlink must be
150  * implemented and provided by the
151  * module agent. The handler has to derive the original equipment id from the
152  * data type and specification of the block. The offline reconstruction does
153  * not need to be changed or adapted at all. See AliRawReaderHLT for details.
154  *
155  * @subsection sec_alihltreconstructor_hltout_rawstream Preprocessed Raw HLTOUT data
156  * Handlers of type \link AliHLTModuleAgent::AliHLTOUTHandlerType kRawStream \endlink
157  * are foreseen though at the time of writing (May 08) the
158  * concept is not fixed. Advanced data compression algorithms can produce a
159  * raw data format which is not convertible into the raw DDL data, e.g. lossy
160  * compression techniques storing clusters parametrized regarding to tracks. A
161  * specific RawStream is needed here since the data is detector specific and the
162  * first stage of the offline reconstruction might need some adaptions.
163  *
164  * @subsection sec_alihltreconstructor_hltout_chain HLTOUT data fed into a chain
165  * At the time of writing (May 08), handler type 
166  * \link AliHLTModuleAgent::AliHLTOUTHandlerType kChain \endlink
167  * is foreseen but not yet implemented. Has to be discussed.
168  *
169  * @subsection sec_alihltreconstructor_hltout_proprietary Proprietary HLTOUT data
170  * This is a handler of proprietary detector data. Handlers of type 
171  * \link AliHLTModuleAgent::AliHLTOUTHandlerType kProprietary \endlink
172  * do not have any standard output to the framework. Data can be processed and
173  * stored to files.
174  *
175  * @section sec_alihltreconstructor_helper Tools and helper functions
176  * Some helper functions of the AliHLTReconstruction can be used in stand-alone
177  * mode. Remember to Init() the reconstructor.
178  * <pre>
179  * {
180  * gSystem->Load("libHLTrec.so");
181  * AliHLTReconstructor rec;
182  * rec.Init();
183  * // do something
184  * }
185  * </pre>
186  * @subsection sec_alihltreconstructor_hltout_standalone Stand-alone HLTOUT processing
187  * - HLTOUT processing from a digit file:
188  * <pre>
189  *  void ProcessHLTOUT(const char*, AliESDEvent*) const;
190  * </pre>
191  * - HLTOUT processing from an AliRawReader
192  * <pre>
193  *  void ProcessHLTOUT(AliRawReader*, AliESDEvent*) const;
194  * </pre>
195  *
196  * @ingroup alihlt_aliroot_reconstruction
197  * @section sec_alihltreconstructor_members Class members
198  */
199 class AliHLTReconstructor: public AliReconstructor {
200 public:
201   /** standard constructor */
202   AliHLTReconstructor();
203   /** constructor */
204   AliHLTReconstructor(const char* options);
205   /** destructor */
206   virtual ~AliHLTReconstructor();
207
208   /** init the reconstructor */
209   void Init();
210
211   /** init the reconstructor */
212   void Init(const char* options);
213
214   /**
215    * Init streamer infos for the relevent classes to be extracted from HLT raw
216    * data payload. Reads the info from HLT/Calib/StreamerInfo
217    */
218   int InitStreamerInfos();
219
220   /**
221    * Init streamer infos for the relevant classes to be extracted from HLT raw
222    * data payload.
223    */
224   int InitStreamerInfos(TObjArray* pSchemas) const;
225
226   /**
227    * Build the CTP_TRIGGER_CLASSES string from CTP trigger configuration
228    */
229   int BuildCTPTriggerClassString(TString& triggerclasses) const;
230
231   /**
232    * This Reconstructor function is not applicable for the AliHLTReconstructor
233    * as it gets a detector specific digits tree. But HLT processes all detectors.
234    * Furthermore it's purely simulated data. <br>
235    * The function forwards to the default bahavior of AliReconstructor but gives
236    * a warning if there were options set, i.e. the user runs customized
237    * reconstruction.
238    *
239    * @note HLT reconstruction on simulated data is processed at the end of
240    * simulation. <br>
241    */
242   void Reconstruct(TTree* digitsTree, TTree* clustersTree) const;
243
244   /**
245    * Reconstruction from RAW data.
246    * The rawReader holds data for all detectors and this version of Reconstruct
247    * is thus applicable for the HLT. The clustersTree is just ignored.
248    */
249   void Reconstruct(AliRawReader* rawReader, TTree* clustersTree) const;
250
251   /**
252    * This function treats the simulated HLTOUT data.
253    * Opens a handler for simulated HLTOUT data and forwards to ::ProcessHLTOUT.
254    */
255   void FillESD(TTree* digitsTree, TTree* clustersTree, AliESDEvent* esd) const;
256
257   /**
258    * Process the raw HLTOUT data and fill ESD.
259    * Opens a handler for raw HLTOUT data and forwards to ::ProcessHLTOUT.
260    */
261   void FillESD(AliRawReader* rawReader, TTree* clustersTree, AliESDEvent* esd) const;
262
263   /**
264    * Process HLTOUT data and fill ESD.
265    * This is the final treatment of the HLTOUT data, either simulated or real.
266    * HLTOUT data is stored in HOMER format, the AliHLTOUT object provides the interface
267    * to the individual data blocks.
268    *
269    * During reconstruction (::Reconstruct), module or user defined chains can be
270    * processed and may add additional data to the HLTOUT object. This data is then
271    * treated in the same way.
272    */
273   void ProcessHLTOUT(AliHLTOUT* pHLTOUT, AliESDEvent* esd, bool bVerbose=false) const;
274
275   /**
276    * Process HLTOUT data.
277    * Open digit file and process the HLTOUT digit data.
278    * This function is mostly intended for debugging purposes and stand-alone
279    * processing of the output from the simulation. Loops over all events.
280    * @param digitFile        path of the digit file
281    * @param pEsd             optional ESD to be filled
282    */
283   void ProcessHLTOUT(const char* digitFile="HLT.Digits.root", AliESDEvent* pEsd=NULL) const;
284
285   /**
286    * Process HLTOUT data.
287    * Process the HLTOUT from the raw reader.
288    * This function is mostly intended for debugging purposes and stand-alone
289    * processing of simulated or real raw data. 
290    * \em Note: Loops over all events, i.e. the current event of the the raw
291    * reader will change. Not to be called inside the normal AliRoot processsing.
292    * @param pRawReader       raw reader instance
293    * @param pEsd             optional ESD to be filled
294    */
295   void ProcessHLTOUT(AliRawReader* pRawReader, AliESDEvent* pEsd=NULL) const;
296
297   /**
298    * Print a short info about the HLTOUT content.
299    */
300   void PrintHLTOUTContent(AliHLTOUT* pHLTOUT) const;
301
302   enum {
303     /// ignore the blocks from the HLTOUT payload
304     kAliHLTReconstructorIgnoreHLTOUT = 0x1,
305     kAliHLTReconstructorIgnoreCTP = 0x2,
306     kAliHLTReconstructorLastFlag
307   };
308
309 private:
310   /** copy constructor prohibited */
311   AliHLTReconstructor(const AliHLTReconstructor& src);
312   /** assignment operator prohibited */
313   AliHLTReconstructor& operator=(const AliHLTReconstructor& src);
314
315   /** function pointer: processing of HLTOUT data */
316   void (*fFctProcessHLTOUT)(); //!transient
317
318   /** ESD manger instance for this reconstruction */
319   AliHLTEsdManager* fpEsdManager; //!transient
320
321   /** base class for AliRoot HLT plugins */
322   AliHLTPluginBase* fpPluginBase;                                     //!transient
323
324   UInt_t fFlags; //! transient
325
326   static const char* fgkCalibStreamerInfoEntry; //! OCDB path
327
328   ClassDef(AliHLTReconstructor, 7)   // class for the HLT reconstruction
329
330 };
331
332 typedef AliHLTReconstructor AliL3Reconstructor; // for backward compatibility
333
334 #endif