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