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