activating individual HLT simulations from digits and raw data
[u/mrichter/AliRoot.git] / HLT / rec / AliHLTReconstructor.h
CommitLineData
69edd0d6 1//-*- Mode: C++ -*-
2// $Id$
3e820254 3
4#ifndef ALIHLTRECONSTRUCTOR_H
5#define ALIHLTRECONSTRUCTOR_H
c5123824 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 *
3e820254 9
69edd0d6 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
c534985b 16
3e820254 17#include "AliReconstructor.h"
18
19class AliHLTSystem;
20class AliRawReader;
21class AliESDEvent;
c5123824 22class AliHLTOUT;
23class AliHLTEsdManager;
00ddfaca 24class AliHLTPluginBase;
9d4cf2ab 25/**
26 * @defgroup alihlt_aliroot_reconstruction AliRoot reconstruction.
27 *
fb345ed7 28 * @section alihlt_aliroot_reconstruction_intro General Remarks
9d4cf2ab 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
fb345ed7 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
9d4cf2ab 55 *
9d4cf2ab 56 * @ingroup alihlt_system
57 */
3e820254 58
59/**
60 * @class AliHLTReconstructor
9d4cf2ab 61 * AliRoot event reconstruction plug-in for the HLT.
3e820254 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 *
d1d1bbd7 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
3e820254 72 * The default component libraries which are loaded through the initialization
60dd5042 73 * are determined by the @ref AliHLTSystem::fgkHLTDefaultLibs array. The library
74 * loading can be overridden by an option to the AliHLTReconstructor through the
3e820254 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>
1ac82ce6 83 * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formatting -->
3e820254 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>
75cbb181 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
3e820254 94 *
95 * For further information on the AliRoot reconstruction refer to the AliRoot
96 * documentation, namely <tt>AliReconstruction</tt>.
d1d1bbd7 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
9d4cf2ab 133 * The framework implements a standard handling of ESD data
2a0e837e 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
d1d1bbd7 137 * any detector origin. Each ESD block contains the data of only one event,
2a0e837e 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 *
d1d1bbd7 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
9d4cf2ab 147 * handler is of type \link AliHLTModuleAgent::AliHLTOUTHandlerType kEsd \endlink.
2a0e837e 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.
d1d1bbd7 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
9d4cf2ab 161 * \link AliHLTModuleAgent::AliHLTOUTHandlerType kRawReader \endlink must be
162 * implemented and provided by the
d1d1bbd7 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
9d4cf2ab 165 * not need to be changed or adapted at all. See AliRawReaderHLT for details.
d1d1bbd7 166 *
167 * @subsection sec_alihltreconstructor_hltout_rawstream Preprocessed Raw HLTOUT data
9d4cf2ab 168 * Handlers of type \link AliHLTModuleAgent::AliHLTOUTHandlerType kRawStream \endlink
169 * are foreseen though at the time of writing (May 08) the
d1d1bbd7 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
2a0e837e 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:
d1d1bbd7 183 *
184 * @subsection sec_alihltreconstructor_hltout_proprietary Proprietary HLTOUT data
9d4cf2ab 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
7ec2b0ab 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>
9d4cf2ab 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>
d1d1bbd7 210 *
211 * @ingroup alihlt_aliroot_reconstruction
9d4cf2ab 212 * @section sec_alihltreconstructor_members Class members
3e820254 213 */
00ddfaca 214class AliHLTReconstructor: public AliReconstructor {
3e820254 215public:
032c5e5e 216 /** standard constructor */
3e820254 217 AliHLTReconstructor();
032c5e5e 218 /** constructor */
219 AliHLTReconstructor(const char* options);
3e820254 220 /** destructor */
221 virtual ~AliHLTReconstructor();
222
223 /** init the reconstructor */
224 void Init();
225
032c5e5e 226 /** init the reconstructor */
227 void Init(const char* options);
228
3e820254 229 /**
c4ffab2c 230 * Build the CTP_TRIGGER_CLASSES string from CTP trigger configuration
231 */
232 int BuildCTPTriggerClassString(TString& triggerclasses) const;
233
234 /**
3e820254 235 * This Reconstructor function is not applicable for the AliHLTReconstructor
236 * as it gets a detector specific digits tree. But HLT processes all detectors.
7f9ab840 237 * Furthermore it's purely simulated data. <br>
238 * The function forwards to the default bahavior of AliReconstructor but gives
239 * a warning if there were options set, i.e. the user runs customized
240 * reconstruction.
c5123824 241 *
242 * @note HLT reconstruction on simulated data is processed at the end of
243 * simulation. <br>
3e820254 244 */
7f9ab840 245 void Reconstruct(TTree* digitsTree, TTree* clustersTree) const;
3e820254 246
247 /**
248 * Reconstruction from RAW data.
249 * The rawReader holds data for all detectors and this version of Reconstruct
250 * is thus applicable for the HLT. The clustersTree is just ignored.
251 */
252 void Reconstruct(AliRawReader* rawReader, TTree* clustersTree) const;
253
254 /**
c5123824 255 * This function treats the simulated HLTOUT data.
256 * Opens a handler for simulated HLTOUT data and forwards to ::ProcessHLTOUT.
3e820254 257 */
7f9ab840 258 void FillESD(TTree* digitsTree, TTree* clustersTree, AliESDEvent* esd) const;
3e820254 259
260 /**
c5123824 261 * Process the raw HLTOUT data and fill ESD.
262 * Opens a handler for raw HLTOUT data and forwards to ::ProcessHLTOUT.
3e820254 263 */
264 void FillESD(AliRawReader* rawReader, TTree* clustersTree, AliESDEvent* esd) const;
265
c5123824 266 /**
267 * Process HLTOUT data and fill ESD.
268 * This is the final treatment of the HLTOUT data, either simulated or real.
269 * HLTOUT data is stored in HOMER format, the AliHLTOUT object provides the interface
270 * to the individual data blocks.
271 *
272 * During reconstruction (::Reconstruct), module or user defined chains can be
273 * processed and may add additional data to the HLTOUT object. This data is then
274 * treated in the same way.
275 */
b005ef92 276 void ProcessHLTOUT(AliHLTOUT* pHLTOUT, AliESDEvent* esd, bool bVerbose=false) const;
c5123824 277
032c5e5e 278 /**
279 * Process HLTOUT data.
280 * Open digit file and process the HLTOUT digit data.
281 * This function is mostly intended for debugging purposes and stand-alone
282 * processing of the output from the simulation. Loops over all events.
283 * @param digitFile path of the digit file
284 * @param pEsd optional ESD to be filled
285 */
286 void ProcessHLTOUT(const char* digitFile="HLT.Digits.root", AliESDEvent* pEsd=NULL) const;
287
288 /**
289 * Process HLTOUT data.
290 * Process the HLTOUT from the raw reader.
291 * This function is mostly intended for debugging purposes and stand-alone
292 * processing of simulated or real raw data.
293 * \em Note: Loops over all events, i.e. the current event of the the raw
294 * reader will change. Not to be called inside the normal AliRoot processsing.
295 * @param pRawReader raw reader instance
296 * @param pEsd optional ESD to be filled
297 */
298 void ProcessHLTOUT(AliRawReader* pRawReader, AliESDEvent* pEsd=NULL) const;
299
300 /**
301 * Print a short info about the HLTOUT content.
302 */
303 void PrintHLTOUTContent(AliHLTOUT* pHLTOUT) const;
304
3eb6bcbe 305 enum {
306 /// ignore the blocks from the HLTOUT payload
307 kAliHLTReconstructorIgnoreHLTOUT = 0x1,
75cbb181 308 kAliHLTReconstructorIgnoreCTP = 0x2,
3eb6bcbe 309 kAliHLTReconstructorLastFlag
310 };
311
3e820254 312private:
313 /** copy constructor prohibited */
314 AliHLTReconstructor(const AliHLTReconstructor& src);
315 /** assignment operator prohibited */
316 AliHLTReconstructor& operator=(const AliHLTReconstructor& src);
317
c5123824 318 /** ESD manger instance for this reconstruction */
319 AliHLTEsdManager* fpEsdManager; //!transient
320
00ddfaca 321 /** base class for AliRoot HLT plugins */
322 AliHLTPluginBase* fpPluginBase; //!transient
323
3eb6bcbe 324 UInt_t fFlags; //! transient
325
dc5556e5 326 static const char* fgkCalibStreamerInfoEntry; //! OCDB path
327
69edd0d6 328 ClassDef(AliHLTReconstructor, 8) // class for the HLT reconstruction
c5123824 329
3e820254 330};
331
332typedef AliHLTReconstructor AliL3Reconstructor; // for backward compatibility
333
334#endif