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