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 -# @ref tut_hltsystem
  31    -# @ref tut_load_libraries
  32    -# @ref tut_dummy_chain
  33    -# @ref tut_tpc_sector
  34 -# @ref tut_reconstruction
  35    -# @ref tut_module_agent
  36    -# @ref tut_reconstruction_sample
  37
  38 <br>
  39 <br>
  40 @section tut_hltsystem Running Components in the HLT System
  41
  42 @subsection tut_load_libraries Library setup
  43 Component libraries must be loader via the AliHLTComponentHandler
  44 or AliHLTSystem::LoadComponentLibraries. You can run the following
  45 macro from the AliRoot promt.
  46 <pre>
  47 {
  48   AliHLTSystem gHLT;
  49   gHLT.LoadComponentLibraries("libAliHLTUtil.so");
  50 }
  51 </pre>
  52
  53 <br>
  54 @subsection tut_dummy_chain Example: Running a dummy chain
  55 The simplest chain consists of a publisher component, a processor
  56 and a data sink. The AliHLTDummyComponent is a sample component
  57 which just copies a fraction of the input data to the output.
  58 You can run the following macro from the AliRoot promt.
  59 <pre>
  60 {
  61   AliHLTSystem gHLT;
  62   gHLT.LoadComponentLibraries("libAliHLTUtil.so libAliHLTSample.so");
  63   // The AliHLTFilePublisher (component Id \em 'FilePublisher' provides
  64   // the given file (see AliHLTFilePublisher for more options) to the
  65   // subsequent components in the chain.
  66   AliHLTConfiguration publisher("fp1", "FilePublisher", NULL, "-datafile some-data.dat");
  67
  68   // The AliHLTDummyComponent (Id \em 'Dummy') just forwards a certain
  69   // fraction of the input to the output or just repeats the input data
  70   // if percentage > 100
  71   AliHLTConfiguration copy("cp", "Dummy", "fp1", "output_percentage 80");
  72
  73   // The AliHLTFileWriter (Id 'FileWriter') is a data sink. It writes
  74   // all incoming data blocks to files. Several options available.
  75   AliHLTConfiguration sink1("sink1", "FileWriter", "cp", NULL);
  76
  77   // here you specify the top most configuration of the chain. The
  78   // configuration depends on all the parents. The task lisy is build
  79   // according to that.
  80   gHLT.BuildTaskList("sink1");
  81   gHLT.Run();
  82 }
  83 </pre>
  84 @note You have to specify a real file name instead of \em some-data.dat
  85
  86 <br>
  87 @subsection tut_tpc_sector Example: One sector of the TPC
  88 This example builds an analysis chain for TPC sector 0. It works on
  89 simulated data and assumes the ddl files to be present in the current
  90 directory.
  91 <pre>
  92 {
  93   AliHLTSystem gHLT;
  94   // load the component library
  95   gHLT.LoadComponentLibraries("libAliHLTUtil.so libAliHLTRCU.so libAliHLTTPC.so");
  96
  97   // data source components
  98   AliHLTConfiguration fp0("fp0", "FilePublisher", NULL, "-datatype 'DDL_RAW ' 'TPC ' -dataspec 0x00000000"
  99                                                         "-datafile TPC_768.ddl");
 100   AliHLTConfiguration fp1("fp1", "FilePublisher", NULL, "-datatype 'DDL_RAW ' 'TPC ' -dataspec 0x00000101"
 101                                                         "-datafile TPC_769.ddl");
 102   AliHLTConfiguration fp2("fp2", "FilePublisher", NULL, "-datatype 'DDL_RAW ' 'TPC ' -dataspec 0x00000202"
 103                                                         "-datafile TPC_840.ddl");
 104   AliHLTConfiguration fp3("fp3", "FilePublisher", NULL, "-datatype 'DDL_RAW ' 'TPC ' -dataspec 0x00000303"
 105                                                         "-datafile TPC_841.ddl");
 106   AliHLTConfiguration fp4("fp4", "FilePublisher", NULL, "-datatype 'DDL_RAW ' 'TPC ' -dataspec 0x00000404"
 107                                                         "-datafile TPC_842.ddl");
 108   AliHLTConfiguration fp5("fp5", "FilePublisher", NULL, "-datatype 'DDL_RAW ' 'TPC ' -dataspec 0x00000505"
 109                                                         "-datafile TPC_843.ddl");
 110
 111   // cluster finders
 112   AliHLTConfiguration cf0("cf0", "TPCClusterFinderPacked", "fp0", "pp-run rawreadermode 4 timebins 446");
 113   AliHLTConfiguration cf1("cf1", "TPCClusterFinderPacked", "fp1", "pp-run rawreadermode 4 timebins 446");
 114   AliHLTConfiguration cf2("cf2", "TPCClusterFinderPacked", "fp2", "pp-run rawreadermode 4 timebins 446");
 115   AliHLTConfiguration cf3("cf3", "TPCClusterFinderPacked", "fp3", "pp-run rawreadermode 4 timebins 446");
 116   AliHLTConfiguration cf4("cf4", "TPCClusterFinderPacked", "fp4", "pp-run rawreadermode 4 timebins 446");
 117   AliHLTConfiguration cf5("cf5", "TPCClusterFinderPacked", "fp5", "pp-run rawreadermode 4 timebins 446");
 118
 119   // tracker
 120   AliHLTConfiguration tracker("tracker", "TPCSliceTracker", "cf0 cf1 cf2 cf3 cf4 cf5", "pp-run bfield 0.5");
 121
 122   // the data sink component
 123   AliHLTConfiguration writer("writer", "TPCEsdWriter", "tracker", "-datafile AliESDs.root");
 124
 125   gHLT.BuildTaskList("writer");
 126   gHLT.Run();
 127 }
 128 </pre>
 129
 130 @section tut_reconstruction AliRoot reconstruction
 131 The HLT analysis components can be run either in the AliRoot
 132 reconstruction or the HLT online framework.
 133 The integration into the AliRoot reconstruction works via the
 134 @ref AliHLTReconstructor plugin. The intention is to run HLT analysis
 135 chains in AliRoot in the same way as in the online framework, i.e.
 136 the full components are run also from the offline framework rather
 137 than just the algorithm hooked on by a special interface class.
 138 By this one achieves the highest possible compatibility.
 139
 140 We think of the HLT as a 'black box' with data input and output. In
 141 addition there is access to calibration data from OCDB (or the local
 142 HLT copy HCDB). All components can only work on the data they get as
 143 input. As the different detector algorithms/components will run in
 144 separated processes and even on different machines, no data exchange
 145 is possible via global data structures and variables possible.
 146
 147 The AliRoot reconstruction consists mainly of three steps:
 148 -# local event reconstruction: this is usually the place for digit/raw
 149 data conversion to clusters/space points. All the events are processed
 150 at once. If HLT analysis chain are executed in the local event
 151 reconstruction, the chain must contain an output recorder as the ESD
 152 is filled on an event by event basis and the corresponding method called
 153 later.
 154 -# event reconstruction: this is the reconstruction on an event by event
 155 basis. Immediately after the reconstruction, the FillESD method is
 156 called.
 157 -# ESD fill: the reconstructed event is written to the ESD.
 158
 159 @subsection tut_module_agent The Module Agent
 160 Each component library has to implement a module agent in order to be
 161 hooked up to the AliRoot reconstruction system. The agent defines the
 162 features of the libraries and the configurations to be run during the
 163 different steps of the reconstruction. The agent
 164 - can register all components of the library. This is an
 165   alternative to the component registration via global objects (see
 166   @ref alihltcomponent-handling).
 167 - registers HLT configurations (see @ref AliHLTConfiguration)
 168 - specifies the configurations to be run
 169 - specifies additional component libraries required to run the
 170   configurations.
 171
 172 Finally, one global object of the module agent has to be specified in
 173 the source code. All registration and integration into the HLT system
 174 is carried out automatically.
 175
 176 @see
 177     @ref AliHLTModuleAgent for the interface description <br>
 178     @ref AliHLTAgentSample for a sample implementation
 179
 180 @subsection tut_reconstruction_sample The sample library
 181 The libAliHLTSample library provides examples how to implement the
 182 library agent (@ref AliHLTAgentSample), how to add configurations and
 183 define HLT chains for reconstruction.
 184
 185 The sample library is not part of the default libraries loaded by the
 186 HLT steering during reconstruction. The example can be run by the
 187 following macro in AliRoot (provided you have a simulated event in the
 188 current directory):
 189 <pre>
 190 {
 191   AliReconstruction rec;                 // the reconstruction instance
 192   rec.SetRunLocalReconstruction("HLT");  // run local rec only for HLT
 193   rec.SetRunTracking("");                // switch off tracking
 194   rec.SetOption("HLT", "libAliHLTSample.so");
 195   rec.Run();
 196 }
 197 </pre>
 198
 199 The agent defines the following chains:
 200 -# a simple data copying consisting of a
 201    - @ref AliHLTFilePublisher  publishes some data generated before in /tmp
 202    - @ref AliHLTDummyComponent copies a fraction of the incoming data
 203    - @ref AliHLTFileWriter     writes the data input to a file
 204 -# digit publishing from the TPCloader <br>
 205    This chain illustrates how data can be published from the AliRunLoader
 206    in order to be processed by another component (not in the sample chain).
 207    Finally, the @ref AliHLTSampleOfflineSinkComponent is component which is
 208    the backend and has again the AliRoot structures.
 209    - @ref AliHLTLoaderPublisherComponent
 210    - @ref AliHLTSampleOfflineSinkComponent
 211
 212 In the same way any other component library can be integrated into the
 213 AliRoot reconstruction.
 214
 215  */
 216
 217 /* note pad
 218
 219 Making a new module/library
 220
 221 Automatic ROOT dictionary generation:
 222 The automatic ROOT dictionary generation relies on the rule, that the main class
 223 of a header file has the same name as the file (except the prefix).
 224
 225 Troubleshooting:
 226 Error: link requested for unknown class <class name> <library>-LinkDef.h:<line no>
 227 most likely there is no class <class name> defined in the header file <class name>.h*
 228
 229  */
 230 #error Not for compilation
 231 //
 232 // EOF
 233 //