HLT sample applications
[u/mrichter/AliRoot.git] / HLT / SampleLib / tutorial.c
index 808465a..76f64f2 100644 (file)
     @date   
     @brief  HLT examples and tutorial. */
 
-/** @defgroup alihlt_tutorial HLT examples and tutorial
-    @brief HLT examples and tutorial
+/** 
+@defgroup alihlt_tutorial HLT examples and tutorial
 
-    A description will follow ...
-*/
+-# @ref tut_hltsystem
+   -# @ref tut_load_libraries
+   -# @ref tut_dummy_chain
+   -# @ref tut_tpc_sector
+-# @ref tut_reconstruction
+   -# @ref tut_module_agent
+   -# @ref tut_reconstruction_sample
+
+<br>
+<br>
+@section tut_hltsystem Running Components in the HLT System
+
+@subsection tut_load_libraries Library setup
+Component libraries must be loader via the AliHLTComponentHandler
+or AliHLTSystem::LoadComponentLibraries. You can run the following
+macro from the AliRoot promt.
+<pre>
+{
+  AliHLTSystem gHLT;
+  gHLT.LoadComponentLibraries("libAliHLTUtil.so");
+}
+</pre>
+
+<br>
+@subsection tut_dummy_chain Example: Running a dummy chain
+The simplest chain consists of a publisher component, a processor
+and a data sink. The AliHLTDummyComponent is a sample component
+which just copies a fraction of the input data to the output.
+You can run the following macro from the AliRoot promt.
+<pre>
+{
+  AliHLTSystem gHLT;
+  gHLT.LoadComponentLibraries("libAliHLTUtil.so libAliHLTSample.so");
+  AliHLTConfiguration publisher("fp1", "FilePublisher", NULL, "-datafile some-data.dat");
+  AliHLTConfiguration copy("cp", "Dummy", "fp1", "output_percentage 80");
+  AliHLTConfiguration sink1("sink1", "FileWriter", "cp", NULL);
+  gHLT.BuildTaskList(&sink1);
+  gHLT.Run();
+}
+</pre>
+@note You have to specify a real file name instead of \em some-data.dat
+
+<br>
+@subsection tut_tpc_sector Example: One sector of the TPC
+This example builds an analysis chain for TPC sector 0. It works on 
+simulated data and assumes the ddl files to be present in the current
+directory.
+<pre>
+{
+  AliHLTSystem gHLT;
+  // load the component library
+  gHLT.LoadComponentLibraries("libAliHLTUtil.so libAliHLTTPC.so");
+
+  // data source components
+  AliHLTConfiguration fp0("fp0", "FilePublisher", NULL, "-datafile TPC_768.ddl -datatype DDL_RWPK 'TPC '"
+                                                       "-dataspec 0x00000000");
+  AliHLTConfiguration fp1("fp1", "FilePublisher", NULL, "-datafile TPC_769.ddl -datatype DDL_RWPK 'TPC '"
+                                                        "-dataspec 0x00000101");
+  AliHLTConfiguration fp2("fp2", "FilePublisher", NULL, "-datafile TPC_840.ddl -datatype DDL_RWPK 'TPC '"
+                                                        "-dataspec 0x00000202");
+  AliHLTConfiguration fp3("fp3", "FilePublisher", NULL, "-datafile TPC_841.ddl -datatype DDL_RWPK 'TPC '"
+                                                       "-dataspec 0x00000303");
+  AliHLTConfiguration fp4("fp4", "FilePublisher", NULL, "-datafile TPC_842.ddl -datatype DDL_RWPK 'TPC '"
+                                                       "-dataspec 0x00000404");
+  AliHLTConfiguration fp5("fp5", "FilePublisher", NULL, "-datafile TPC_843.ddl -datatype DDL_RWPK 'TPC '"
+                                                       "-dataspec 0x00000505");
+
+  // cluster finders
+  AliHLTConfiguration cf0("cf0", "TPCClusterFinderPacked", "fp0", "pp-run rawreadermode 4 timebins 446");
+  AliHLTConfiguration cf1("cf1", "TPCClusterFinderPacked", "fp1", "pp-run rawreadermode 4 timebins 446");
+  AliHLTConfiguration cf2("cf2", "TPCClusterFinderPacked", "fp2", "pp-run rawreadermode 4 timebins 446");
+  AliHLTConfiguration cf3("cf3", "TPCClusterFinderPacked", "fp3", "pp-run rawreadermode 4 timebins 446");
+  AliHLTConfiguration cf4("cf4", "TPCClusterFinderPacked", "fp4", "pp-run rawreadermode 4 timebins 446");
+  AliHLTConfiguration cf5("cf5", "TPCClusterFinderPacked", "fp5", "pp-run rawreadermode 4 timebins 446");
+
+  // tracker
+  AliHLTConfiguration tracker("tracker", "TPCSliceTracker", "cf0 cf1 cf2 cf3 cf4 cf5", "pp-run bfield 0.5");
+
+  // the data sink component
+  AliHLTConfiguration writer("writer", "TPCEsdWriter", "tracker", "-datafile AliESDs.root");
+
+  gHLT.BuildTaskList(&writer);
+  gHLT.Run();
+}
+</pre>
+    
+@section tut_reconstruction AliRoot reconstruction
+The HLT analysis components can be run either in the AliRoot
+reconstruction or the HLT online framework.
+The integration into the AliRoot reconstruction works via the
+@ref AliHLTReconstructor plugin. The intention is to run HLT analysis
+chains in AliRoot in the same way as in the online framework, i.e.
+the full components are run also from the offline framework rather
+than just the algorithm hooked on by a special interface class.
+By this one achieves the highest possible compatibility.
+
+We think of the HLT as a 'black box' with data input and output. In
+addition there is access to calibration data from OCDB (or the local
+HLT copy HCDB). All components can only work on the data they get as
+input. As the different detector algorithms/components will run in 
+separated processes and even on different machines, no data exchange
+is possible via global data structures and variables possible.
+
+The AliRoot reconstruction consists mainly of three steps:
+-# local event reconstruction: this is usually the place for digit/raw
+data conversion to clusters/space points. All the events are processed
+at once. If HLT analysis chain are executed in the local event
+reconstruction, the chain must contain an output recorder as the ESD
+is filled on an event by event basis and the corresponding method called
+later.
+-# event reconstruction: this is the reconstruction on an event by event
+basis. Immediately after the reconstruction, the FillESD method is
+called.
+-# ESD fill: the reconstructed event is written to the ESD.
+
+@subsection tut_module_agent The Module Agent
+Each component library has to implement a module agent in order to be
+hooked up to the AliRoot reconstruction system. The agent defines the
+features of the libraries and the configurations to be run during the
+different steps of the reconstruction. The agent 
+- can register all components of the library. This is an 
+  alternative to the component registration via global objects (see 
+  @ref alihltcomponent-handling).
+- registers HLT configurations (see @ref AliHLTConfiguration)
+- specifies the configurations to be run
+- specifies additional component libraries required to run the
+  configurations.
+
+Finally, one global object of the module agent has to be specified in
+the source code. All registration and integration into the HLT system
+is carried out automatically.
+
+@see 
+    @ref AliHLTModuleAgent for the interface description <br>
+    @ref AliHLTAgentSample for a sample implementation
+
+@subsection tut_reconstruction_sample The sample library
+The libAliHLTSample library provides examples how to implement the
+library agent (@ref AliHLTAgentSample), how to add configurations and
+define HLT chains for reconstruction. 
+
+The sample library is not part of the default libraries loaded by the
+HLT steering during reconstruction. The example can be run by the
+following macro in AliRoot (provided you have a simulated event in the
+current directory):
+<pre>
+{
+  AliReconstruction rec;                 // the reconstruction instance
+  rec.SetRunLocalReconstruction("HLT");  // run local rec only for HLT 
+  rec.SetRunTracking("");                // switch off tracking
+  rec.SetOption("HLT", "libAliHLTSample.so");
+  rec.Run();
+}
+</pre>
+
+The agent defines the following chains:
+-# a simple data copying consisting of a
+   - @ref AliHLTFilePublisher  publishes some data generated before in /tmp
+   - @ref AliHLTDummyComponent copies a fraction of the incoming data
+   - @ref AliHLTFileWriter     writes the data input to a file
+-# digit publishing from the TPCloader <br>
+   This chain illustrates how data can be published from the AliRunLoader
+   in order to be processed by another component (not in the sample chain).
+   Finally, the @ref AliHLTSampleOfflineSinkComponent is component which is
+   the backend and has again the AliRoot structures.
+   - @ref AliHLTLoaderPublisherComponent
+   - @ref AliHLTSampleOfflineSinkComponent
+
+In the same way any other component library can be integrated into the
+AliRoot reconstruction.
+
+ */
 
 /* note pad