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