Enhanced doxygen documentation
[u/mrichter/AliRoot.git] / HLT / SampleLib / tutorial.c
1 /************************************************************************
2 **
3 ** ALICE HLT project
4 ** Copyright (c) 2005
5 **
6 ** This file is property of and copyright by the Experimental Nuclear 
7 ** Physics Group, Dep. of Physics and Technology
8 ** University of Bergen, Norway, 2004
9 ** This file has been written by Matthias Richter,
10 ** Matthias.Richter@ift.uib.no
11 **
12 ** Permission to use, copy, modify and distribute this software and its  
13 ** documentation strictly for non-commercial purposes is hereby granted  
14 ** without fee, provided that the above copyright notice appears in all  
15 ** copies and that both the copyright notice and this permission notice  
16 ** appear in the supporting documentation. The authors make no claims    
17 ** about the suitability of this software for any purpose. It is         
18 ** provided "as is" without express or implied warranty.                 
19 **
20 *************************************************************************/
21
22 /** @file   tutorial.c
23     @author Matthias Richter
24     @date   
25     @brief  HLT examples and tutorial. */
26
27 /** 
28 @defgroup alihlt_tutorial HLT examples and tutorial
29
30 The HLT analysis components can be run either in the AliRoot
31 framework (simulation and/or reconstruction) or the HLT online
32 framework.
33
34 We think of the HLT as a 'black box' with data input and output. In
35 addition there is access to calibration data from OCDB (or the local
36 HLT copy HCDB). All components can only work on the data they get as
37 input. As the different detector algorithms/components will run in 
38 separate processes and even on different machines, no data exchange
39 is possible via global data structures and variables.
40
41 HLT chains in the AliRoot framework are described by means of
42 AliHLTConfiguration.
43
44 -# @ref tut_hltsystem
45    -# @ref tut_load_libraries
46    -# @ref tut_dummy_chain
47    -# @ref tut_tpc_sector
48 -# @ref tut_simulation
49 -# @ref tut_reconstruction
50    -# @ref tut_module_agent
51    -# @ref tut_reconstruction_sample
52    -# @ref tut_reconstruction_custom
53 -# @ref tut_alirawreaderhlt
54 -# @ref tut_macros 
55
56 <br>
57 <hr width="75%">
58 <br>
59 @section tut_hltsystem Running Components in the HLT System
60
61 @subsection tut_load_libraries Library setup
62 Component libraries must be loader via the AliHLTComponentHandler
63 or AliHLTSystem::LoadComponentLibraries. You can run the following
64 macro from the AliRoot promt.
65 <pre>
66 {
67   AliHLTSystem gHLT;
68   gHLT.LoadComponentLibraries("libAliHLTUtil.so");
69 }
70 </pre>
71
72 <br>
73 @subsection tut_dummy_chain Example: Running a dummy chain
74 The simplest chain consists of a publisher component, a processor
75 and a data sink. The AliHLTDummyComponent is a sample component
76 which just copies a fraction of the input data to the output.
77 You can run the following macro from the AliRoot promt.
78 <pre>
79 {
80   AliHLTSystem gHLT;
81   gHLT.LoadComponentLibraries("libAliHLTUtil.so libAliHLTSample.so");
82   // The AliHLTFilePublisher (component Id \em 'FilePublisher' provides
83   // the given file (see AliHLTFilePublisher for more options) to the
84   // subsequent components in the chain.
85   AliHLTConfiguration publisher("fp1", "FilePublisher", NULL, "-datatype 'DUMMYDAT' 'SMPL' -datafile some-data.dat");
86
87   // The AliHLTDummyComponent (Id \em 'Dummy') just forwards a certain
88   // fraction of the input to the output or just repeats the input data
89   // if percentage > 100
90   AliHLTConfiguration copy("cp", "Dummy", "fp1", "output_percentage 80");
91
92   // The AliHLTFileWriter (Id 'FileWriter') is a data sink. It writes
93   // all incoming data blocks to files. Several options available.
94   AliHLTConfiguration sink1("sink1", "FileWriter", "cp", NULL);
95
96   // here you specify the top most configuration of the chain. The
97   // configuration depends on all the parents. The task lisy is build
98   // according to that.
99   gHLT.BuildTaskList("sink1");
100   gHLT.Run();
101 }
102 </pre>
103 @note You have to specify a real file name instead of \em some-data.dat
104
105 <br>
106 @subsection tut_tpc_sector Example: One sector of the TPC
107 This example builds an analysis chain for TPC sector 0. It works on 
108 simulated data and assumes the ddl files to be present in the current
109 directory.
110 <pre>
111 {
112   AliHLTSystem gHLT;
113   // load the component library
114   gHLT.LoadComponentLibraries("libAliHLTUtil.so libAliHLTRCU.so libAliHLTTPC.so");
115
116   // data source components
117   AliHLTConfiguration fp0("fp0", "FilePublisher", NULL, "-datatype 'DDL_RAW ' 'TPC ' -dataspec 0x00000000 "
118                                                         "-datafile TPC_768.ddl");
119   AliHLTConfiguration fp1("fp1", "FilePublisher", NULL, "-datatype 'DDL_RAW ' 'TPC ' -dataspec 0x00000101 "
120                                                         "-datafile TPC_769.ddl");
121   AliHLTConfiguration fp2("fp2", "FilePublisher", NULL, "-datatype 'DDL_RAW ' 'TPC ' -dataspec 0x00000202 "
122                                                         "-datafile TPC_840.ddl");
123   AliHLTConfiguration fp3("fp3", "FilePublisher", NULL, "-datatype 'DDL_RAW ' 'TPC ' -dataspec 0x00000303 "
124                                                         "-datafile TPC_841.ddl");
125   AliHLTConfiguration fp4("fp4", "FilePublisher", NULL, "-datatype 'DDL_RAW ' 'TPC ' -dataspec 0x00000404 "
126                                                         "-datafile TPC_842.ddl");
127   AliHLTConfiguration fp5("fp5", "FilePublisher", NULL, "-datatype 'DDL_RAW ' 'TPC ' -dataspec 0x00000505 "
128                                                         "-datafile TPC_843.ddl");
129
130   // cluster finders
131   AliHLTConfiguration cf0("cf0", "TPCClusterFinderPacked", "fp0", "pp-run rawreadermode 4 timebins 446");
132   AliHLTConfiguration cf1("cf1", "TPCClusterFinderPacked", "fp1", "pp-run rawreadermode 4 timebins 446");
133   AliHLTConfiguration cf2("cf2", "TPCClusterFinderPacked", "fp2", "pp-run rawreadermode 4 timebins 446");
134   AliHLTConfiguration cf3("cf3", "TPCClusterFinderPacked", "fp3", "pp-run rawreadermode 4 timebins 446");
135   AliHLTConfiguration cf4("cf4", "TPCClusterFinderPacked", "fp4", "pp-run rawreadermode 4 timebins 446");
136   AliHLTConfiguration cf5("cf5", "TPCClusterFinderPacked", "fp5", "pp-run rawreadermode 4 timebins 446");
137
138   // tracker
139   AliHLTConfiguration tracker("tracker", "TPCSliceTracker", "cf0 cf1 cf2 cf3 cf4 cf5", "-pp-run -bfield 0.5");
140
141   // the data sink component
142   AliHLTConfiguration writer("writer", "TPCEsdWriter", "tracker", "-datafile AliHLTTPCESDs.root");
143
144   gHLT.BuildTaskList("writer");
145   gHLT.Run();
146 }
147 </pre>
148
149 <br>
150 <hr width="75%">
151 <br>
152
153 @section tut_reconstruction AliRoot reconstruction
154 The integration into the AliRoot reconstruction works via the
155 @ref AliHLTReconstructor plugin. The intention is to run HLT analysis
156 chains in AliRoot in the same way as in the online framework, i.e.
157 the full components are run also from the offline framework rather
158 than just the algorithm hooked on by a special interface class.
159 By this one achieves the highest possible compatibility.
160
161 The AliRoot reconstruction consists mainly of three steps:
162 -# local event reconstruction: this is usually the place for digit/raw
163 data conversion to clusters/space points. All the events are processed
164 at once. If HLT analysis chain are executed in the local event
165 reconstruction, the chain must contain an output recorder as the ESD
166 is filled on an event by event basis and the corresponding method called
167 later.
168 -# event reconstruction: this is the reconstruction on an event by event
169 basis. Immediately after the reconstruction, the FillESD method is
170 called.
171 -# ESD fill: the reconstructed event is written to the ESD.
172
173 Regarding the HLT, all analysis is supposed to run on-line on the HLT farm.
174 Thus, only the processing of the HLTOUT data is necessary during the
175 default reconstruction. However, it is possible to run HLT chains embedded
176 into AliReconstruction mainly for the purpose of debugging and the
177 development cycle.
178
179 The actual chains to be run and the HLTOUT handlers to be applied depend
180 on the HLT library modules which are loaded to the system. There is a
181 default collection of libraries defined in AliHLTSystem::fgkHLTDefaultLibs.
182 The default libraries are loaded if nothing else is specified. The libraries
183 implement \em agents (AliHLTModuleAgent childs) describing the properties
184 of a module.
185
186 A specific library can be chosen like (provided you have a simulated
187 event in the current directory):
188 <pre>
189 {
190   AliReconstruction rec;                 // the reconstruction instance
191   rec.SetRunLocalReconstruction("HLT");  // run local rec only for HLT 
192   rec.SetRunTracking("");                // switch off tracking
193   rec.SetFillESD("HLT");                 // 
194   rec.SetOption("HLT", "libAliHLTSample.so loglevel=0x7c");
195   rec.Run();
196 }
197 </pre>
198
199 @subsection tut_module_agent The Module Agent
200 Each component library has to implement a module agent in order to be
201 hooked up to the AliRoot reconstruction or simulation. The agent defines
202 the features of the libraries and the configurations to be run during the
203 different steps of the reconstruction. The agent 
204 - can register all components of the library. This is an 
205   alternative to the component registration via global objects (see 
206   @ref alihltcomponent-handling).
207 - registers HLT configurations (see @ref AliHLTConfiguration)
208 - specifies the configurations to be run
209 - specifies additional component libraries required to run the
210   configurations.
211 - provides a preprocessor (see AliHLTModulePreprocessor /
212                            AliHLTPreprocessor)
213 - provides handlers and handler descriptions for HLTOUT data blocks.
214
215 Finally, one global object of the module agent has to be specified in
216 the source code. All registration and integration into the HLT system
217 is carried out automatically.
218
219 @see 
220     @ref AliHLTModuleAgent for the interface description <br>
221     @ref AliHLTAgentSample for a sample implementation
222
223 @subsection tut_reconstruction_sample The sample library
224 The libAliHLTSample library provides examples how to implement the
225 library agent (@ref AliHLTAgentSample), how to add configurations and
226 define HLT chains for reconstruction. 
227
228 The sample library is not part of the default libraries loaded by the
229 HLT steering during reconstruction. The example can be run by the
230 following macro macro above.
231
232 The agent defines the following chains:
233 -# a simple data copying consisting of a
234    - @ref AliHLTFilePublisher  publishes some data generated before in /tmp
235    - @ref AliHLTDummyComponent copies a fraction of the incoming data
236    - @ref AliHLTFileWriter     writes the data input to a file
237 -# digit publishing from the TPCloader <br>
238    This chain illustrates how data can be published from the AliRunLoader
239    in order to be processed by another component (not in the sample chain).
240    Finally, the @ref AliHLTSampleOfflineSinkComponent is component which is
241    the backend and has again the AliRoot structures.
242    - @ref AliHLTLoaderPublisherComponent
243    - @ref AliHLTSampleOfflineSinkComponent
244
245 In the same way any other component library can be integrated into the
246 AliRoot reconstruction.
247
248 @subsection tut_reconstruction_custom Running a custom HLT chain
249 The default configurations from the library modules can be overridden by
250 custom configurations by means of options specified to AliReconstruction.
251 - <tt>config=\em macro</tt><br> a configuration macro. The macro is a normal
252   ROOT macro defining HLT component configurations by means of
253   AliHLTConfiguration
254 - <tt>chains=\em chains</tt><br> a comma separated list of chains to be run.
255   A chain is defined by the topmost configuration.
256
257 \b Note: The file publisher needs a file to read, either you replace
258 \em some-data.dat with the path of an existing file or just create a
259 dummy file in the current working directory. Futhermore, there has to be at
260 least one simulated event since AliReconstruction relies on a couple of files
261 in the folder.
262 <pre>
263 {
264   AliReconstruction rec;                 // the reconstruction instance
265   rec.SetInput("./");                    // to be independent of galice.root
266   rec.SetLoadAlignFromCDB(kFALSE);
267   rec.SetFillTriggerESD(kFALSE);
268   rec.SetRunQA(kFALSE);
269   rec.SetRunVertexFinder(kFALSE);
270   rec.SetRunLocalReconstruction("HLT");  // run local rec only for HLT 
271   rec.SetRunTracking("");                // switch off tracking
272   rec.SetFillESD("HLT");                 // 
273   rec.SetOption("HLT", "libAliHLTSample.so libAliHLTUtil.so "
274                        "config=$ALICE_ROOT/HLT/exa/conf-sample.C "
275                        "chains=sink");
276   //rec.SetEventRange(0,0);
277   rec.Run();
278 }
279 </pre>
280
281 @see
282 - conf-sample.C
283
284 <br>
285 <hr width="75%">
286 <br>
287
288 @section tut_simulation AliRoot simulation
289 In order to simulate the behavior of HLT analysis chains and to
290 include this functionality, HLT reconstruction can be embedded
291 into AliRoot simulation. As a matter of fact, HLT always reconstructs
292 data, <em><b>HLT simulation</b></em> means <em><b>HLT reconstruction
293 embedded into AliRoot</b></em>.
294
295 The HLT simulation is run at the last step of the AliSimulation, the
296 setup to be run depends on the available plugins as described in section
297 @ref tut_reconstruction. The options for the HLT simulation can be set
298 with the <tt>AliSimulation::SetRunHLT</tt> function.
299 <pre>
300   AliSimulation sim;
301   ...
302   sim.SetRunHLT("libAliHLTSample.so loglevel=0x7c");
303 </pre>
304
305 Options:
306 - <tt>config=\em macro</tt><br> a configuration macro. The macro is a normal
307   ROOT macro defining HLT component configurations by means of
308   AliHLTConfiguration
309 - <tt>chains=\em chains</tt><br> a comma separated list of chains to be run.
310   A chain is defined by the topmost configuration.
311 - <tt>rawfile=\em chains</tt><br> provide a raw reader to the HLT simulation.
312   Some chains work solely on raw data. The data needs to be simulated before
313   and a RawReader is created internally to provide the data to the source
314   components.
315 - <tt>loglevel=\em 0x7c</tt><br> default loglevel is 0x79, only Warnings and
316   higher are printed. 0x7c also makes the Info messages visible.
317
318 @see
319   - sim-hlt-rawddl.C for example
320
321
322 <br>
323 <hr width="75%">
324 <br>
325
326 @section tut_alirawreaderhlt Replacing reconstruction input by data from the HLT
327 The HLTOUT data can contain data blocks which obey exactly the raw DDL 
328 format of a detector. E.g. selective readout components or loss-less
329 compression algorithms allow to provide a sub sample of the original data.
330 All data from the HLT is transferred via the 10 HLT DDL links, a redirection
331 mechanism is necessary to replace the original detector input by the data
332 from HLTOUT. The replacements works by means of the AliRawReaderHLT and
333 needs the following modules:
334 -# Implementation of an AliHLTOUTHandlerEquId child class<br>
335    A handler of this type is necessary to determine the equipment Id of a
336    data block from the data type and specification.
337 <pre>
338   class AliHLTSampleRawDataHandler : public AliHLTOUTHandlerEquId {
339   public:
340     // ... constructors and destructor
341     &nbsp;
342     // overloaded AliHLTOUTHandlerEquId::ProcessData(AliHLTOUT*)
343     int ProcessData(AliHLTOUT* pData);
344   };
345 </pre>
346   Alternatively the AliHLTOUTHandlerEquId can be used directly. It implements
347   a default processing.
348 -# Adjust module agent
349    The module agent needs to provide the handler and the description of the
350    handler and has to implement the following functions: 
351 <pre>
352    // see AliHLTAgentSample::GetHandlerDescription()
353    int GetHandlerDescription(AliHLTComponentDataType,
354                              AliHLTUInt32_t,
355                              AliHLTOUTHandlerDesc&) const;
356 &nbsp;   
357    // see AliHLTAgentSample::GetOutputHandler()
358    AliHLTOUTHandler* GetOutputHandler(AliHLTComponentDataType,
359                                       AliHLTUInt32_t);
360    &nbsp;   
361    // see AliHLTAgentSample::DeleteOutputHandler()
362    int DeleteOutputHandler(AliHLTOUTHandler*);
363 </pre>
364 -# Set the HLT input
365    The AliReconstruction class handles the redirection transparently by
366    use of the AliRawReaderHLT.
367 <pre>
368    AliReconstruction rec;
369    // ....
370    rec.SetUseHLTData("ITSSDD");
371 </pre>
372 -# Run
373    Run the reconstruction as normal
374
375 @see
376    - AliHLTReconstructor
377    - AliRawReaderHLT
378    - rec-from-hltout.C
379
380 <br>
381 <hr width="75%">
382 <br>
383
384 @section tut_macros Example macros
385  */
386
387
388 /* note pad
389
390 Making a new module/library
391
392 Automatic ROOT dictionary generation:
393 The automatic ROOT dictionary generation relies on the rule, that the main class
394 of a header file has the same name as the file (except the prefix).
395
396 Troubleshooting:
397 Error: link requested for unknown class <class name> <library>-LinkDef.h:<line no>
398 most likely there is no class <class name> defined in the header file <class name>.h*
399
400  */
401 #error Not for compilation
402 //
403 // EOF
404 //