]>
Commit | Line | Data |
---|---|---|
33791895 | 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 | Regarding HLT, all analysis is supposed to run on-line on the HLT farm. | |
162 | Thus, only the processing of the HLTOUT data is necessary during the | |
163 | default reconstruction. However, it is possible to run HLT chains embedded | |
164 | into AliReconstruction mainly for the purpose of debugging and the | |
165 | development cycle. | |
166 | ||
167 | The AliRoot reconstruction consists mainly of three steps which | |
168 | are executed on an event by event basis: | |
169 | -# event reconstruction: this is usually the place for digit/raw | |
170 | data conversion to clusters/space points. HLT chains can be executed | |
171 | in the event reconstruction for raw data. HLT Reconstruction from | |
172 | digit data is not supported. | |
173 | -# tracking: the complete reconstruction on an event by event | |
174 | basis. | |
175 | -# ESD filling: the reconstructed event is written to the ESD. The | |
176 | HLTOUT is processed in this step. All output data blocks produced by | |
177 | during the HLT reconstruction are added to the HLTOUT collection | |
178 | and are treated as they would have come from the detector. | |
179 | ||
180 | Note: The AliRoot reconstruction scheme has been changed in Sep 2007 | |
181 | (revision 20822). Formerly, a stage "LocalEventReconstruction" of | |
182 | AliReconstruction was looping over all events and running the event | |
183 | reconstruction in one go. | |
184 | ||
185 | The actual HLT chains to be run and the HLTOUT handlers to be applied depend | |
186 | on the HLT library modules which are loaded to the system. There is a | |
187 | default collection of libraries defined in AliHLTSystem::fgkHLTDefaultLibs. | |
188 | The default libraries are loaded if nothing else is specified. The libraries | |
189 | implement \em agents (AliHLTModuleAgent childs) describing the properties | |
190 | of a module. | |
191 | ||
192 | A specific library can be chosen like (provided you have a simulated | |
193 | event in the current directory): | |
194 | <pre> | |
195 | { | |
196 | AliReconstruction rec; // the reconstruction instance | |
197 | rec.SetInput("raw.root"); // choose some raw data | |
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> | |
205 | Please note the specification of raw data input. HLT reconstruction can | |
206 | only run on raw data, either real or simulated. | |
207 | ||
208 | HLT reconstruction on simulated digit data must be run embedded into | |
209 | @ref tut_simulation. | |
210 | ||
211 | @subsection tut_module_agent The Module Agent | |
212 | Each component library has to implement a module agent in order to be | |
213 | hooked up to the AliRoot reconstruction or simulation. The agent defines | |
214 | the features of the libraries and the configurations to be run during the | |
215 | different 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. | |
223 | - provides a preprocessor (see AliHLTModulePreprocessor / | |
224 | AliHLTPreprocessor) | |
225 | - provides handlers and handler descriptions for HLTOUT data blocks. | |
226 | ||
227 | Finally, one global object of the module agent has to be specified in | |
228 | the source code. All registration and integration into the HLT system | |
229 | is 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 | |
236 | The libAliHLTSample library provides examples how to implement the | |
237 | library agent (@ref AliHLTAgentSample), how to add configurations and | |
238 | define HLT chains for reconstruction. | |
239 | ||
240 | The sample library is not part of the default libraries loaded by the | |
241 | HLT steering during reconstruction. The example can be run by the | |
242 | following macro macro above. | |
243 | ||
244 | The 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 | ||
257 | In the same way any other component library can be integrated into the | |
258 | AliRoot reconstruction. | |
259 | ||
260 | @subsection tut_reconstruction_custom Running a custom HLT chain | |
261 | The default configurations from the library modules can be overridden by | |
262 | custom 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 | |
271 | dummy file in the current working directory. Futhermore, there has to be at | |
272 | least one simulated event since AliReconstruction relies on a couple of files | |
273 | in 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 | ||
296 | <br> | |
297 | <hr width="75%"> | |
298 | <br> | |
299 | ||
300 | @section tut_simulation AliRoot simulation | |
301 | In order to simulate the behavior of HLT analysis chains and to | |
302 | include this functionality, HLT reconstruction can be embedded | |
303 | into AliRoot simulation. As a matter of fact, HLT always reconstructs | |
304 | data, <em><b>HLT simulation</b></em> means <em><b>HLT reconstruction | |
305 | embedded into AliRoot</b></em>. | |
306 | ||
307 | The HLT simulation is run at the last step of the AliSimulation, the | |
308 | setup 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 | |
310 | with the <tt>AliSimulation::SetRunHLT</tt> function. | |
311 | <pre> | |
312 | AliSimulation sim; | |
313 | ... | |
314 | sim.SetRunHLT("libAliHLTSample.so loglevel=0x7c"); | |
315 | </pre> | |
316 | ||
317 | Options: | |
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 | ||
333 | ||
334 | <br> | |
335 | <hr width="75%"> | |
336 | <br> | |
337 | ||
338 | @section tut_alirawreaderhlt Replacing reconstruction input by data from the HLT | |
339 | The HLTOUT data can contain data blocks which obey exactly the raw DDL | |
340 | format of a detector. E.g. selective readout components or loss-less | |
341 | compression algorithms allow to provide a sub sample of the original data. | |
342 | All data from the HLT is transferred via the 10 HLT DDL links, a redirection | |
343 | mechanism is necessary to replace the original detector input by the data | |
344 | from HLTOUT. The replacements works by means of the AliRawReaderHLT and | |
345 | needs 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 | | |
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 | | |
369 | // see AliHLTAgentSample::GetOutputHandler() | |
370 | AliHLTOUTHandler* GetOutputHandler(AliHLTComponentDataType, | |
371 | AliHLTUInt32_t); | |
372 | | |
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 | ||
392 | <br> | |
393 | <hr width="75%"> | |
394 | <br> | |
395 | ||
396 | @section tut_macros Example macros | |
397 | */ | |
398 | ||
399 | ||
400 | /* note pad | |
401 | ||
402 | Making a new module/library | |
403 | ||
404 | Automatic ROOT dictionary generation: | |
405 | The automatic ROOT dictionary generation relies on the rule, that the main class | |
406 | of a header file has the same name as the file (except the prefix). | |
407 | ||
408 | Troubleshooting: | |
409 | Error: link requested for unknown class <class name> <library>-LinkDef.h:<line no> | |
410 | most likely there is no class <class name> defined in the header file <class name>.h* | |
411 | ||
412 | */ | |
413 | #error Not for compilation | |
414 | // | |
415 | // EOF | |
416 | // |