adding further optimized compression format with additional 15% compression ratio...
[u/mrichter/AliRoot.git] / HLT / TPCLib / comp / AliHLTTPCDataCompressionComponent.h
1 //-*- Mode: C++ -*-
2 // $Id$
3 #ifndef ALIHLTTPCDATACOMPRESSIONCOMPONENT_H
4 #define ALIHLTTPCDATACOMPRESSIONCOMPONENT_H
5 //* This file is property of and copyright by the ALICE HLT Project        * 
6 //* ALICE Experiment at CERN, All rights reserved.                         *
7 //* See cxx source for full Copyright notice                               *
8
9 /// @file   AliHLTTPCDataCompressionComponent.h
10 /// @author Matthias Richter
11 /// @date   2011-08-08
12 /// @brief  TPC component for data compression
13 ///
14
15 #include "AliHLTProcessor.h"
16 #include "TString.h"
17 #include "AliHLTTrackGeometry.h"
18 #include "AliHLTSpacePointContainer.h"
19 #include <vector>
20
21 class AliHLTGlobalBarrelTrack;
22 class AliHLTComponentBenchmark;
23 class AliHLTSpacePointContainer;
24 class AliHLTDataDeflater;
25 class AliHLTTPCClusterTransformation;
26 class TH1F;
27
28 /**
29  * @class AliHLTTPCDataCompressionComponent
30  * One single component to carry out different types and levels of compression
31  * of TPC data.
32  *
33  * <h2>General properties:</h2>
34  * The component subscribes to the output of the HW cluster finder (emulator)
35  * and performs various types of dat compressions. For each input block a
36  * block of compressed clusters is created. If track model compression is
37  * enabled, all clusters associated to a track are stored in a separate
38  * block together with the tracks. Those clusters are removed from the cluster
39  * blocks of the individual partitions.
40  *
41  * Component ID: \b TPCDataCompressor      <br>
42  * Library: \b libAliHLTTPC.so     <br>
43  * Input Data Types:  <br>
44  *  -  AliHLTTPCDefinitions::fgkHWClustersDataType
45  *  -  AliHLTTPCDefinitions::fgkClustersDataType
46  *  -  kAliHLTDataTypeTrack|kAliHLTDataOriginTPC
47  * Output Data Types: none <br>
48  *
49  * <h2>Data Formats</h2>
50  * Two formats for compressed clusters can be used.
51  * <h3>Format v1</h3>
52  * Format v1 stores the cluster parameters with the following precision:
53  * <pre>
54  *   padrow number & local padrow in partition    &   6 \\ 
55  *   pad position  & pitch 0.4/0.6 cm -> 1/60     &  14 \\ 
56  *   timebin       & 0.25cm/timebin   -> 1/25     &  15 \\ 
57  *   sigmaY2       &                              &   8 \\ 
58  *   sigmaZ2       &                              &   8 \\ 
59  *   total charge  & encoded 10bit number         &   8 \\ 
60  *   max charge    & encoded 16bit number         &  11 \\ 
61  * <pre>
62  * For the padrow, only the difference to the last padrow is stored. The
63  * clusters are ordered by padrow such that there are only positive differences.
64  *
65  * <h3>Format v2</h3>
66  * Format v2 uses the same parameters as v1 but treats single-pad clusters
67  * specially. Furthermore it stores the differences of pad and time with respect
68  * to the previous cluster. The difference is calculated on integers after the
69  * scale and lossy conversion of the float values to integer numbers. Format v2
70  * prepares all parameters for optimal huffman compression.
71  *
72  * <h2>Mandatory arguments:</h2>
73  * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formatting -->
74  *
75  * <h2>Optional arguments:</h2>
76  * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formatting -->
77  * \li -mode     <i> number  </i> <br>
78  *      compression mode                                             <br>
79  *      1 compressed format version 1                                <br>
80  *      2 compressed format version 1 & track model compression      <br>
81  *      3 compressed format version 2                                <br>
82  *      4 compressed format version 2 & track model compression      <br>
83  * \li -deflater-mode     <i> number  </i>                           <br>
84  *      data deflater mode                                           <br>
85  *      0 no data deflation                                          <br>
86  *      1 simple deflation (AliHLTDataDeflaterSimple)                <br>
87  *      2 huffman deflation (AliHLTDataDeflaterHuffman)              <br>
88  * \li -histogram-file     <i> file  </i>                            <br>
89  *      file to store internal histograms at the end
90  *
91  * <h2>Configuration:</h2>
92  * <!-- NOTE: ignore the \li. <i> and </i>: it's just doxygen formatting -->
93  *
94  * <h2>Default CDB entries:</h2>
95  * - HLT/ConfigTPC/TPCDataCompressor
96  * - HLT/ConfigTPC/TPCDataCompressorHuffmanTables
97  *
98  * <h2>Performance:</h2>
99  *
100  * <h2>Memory consumption:</h2>
101  *
102  * <h2>Output size:</h2>
103  *
104  *
105  * @ingroup alihlt_tpc
106  */
107 class AliHLTTPCDataCompressionComponent : public AliHLTProcessor {
108 public:
109   /// standard constructor
110   AliHLTTPCDataCompressionComponent();
111   /// destructor
112   ~AliHLTTPCDataCompressionComponent();
113
114   /// inherited from AliHLTComponent: id of the component
115   virtual const char* GetComponentID();
116
117   /// inherited from AliHLTComponent: list of data types in the vector reference
118   void GetInputDataTypes( AliHLTComponentDataTypeList& );
119
120   /// inherited from AliHLTComponent: output data type of the component.
121   AliHLTComponentDataType GetOutputDataType();
122
123   /// inherited from AliHLTComponent: multiple output data types of the component.
124   int GetOutputDataTypes(AliHLTComponentDataTypeList& tgtList);
125
126   /// inherited from AliHLTComponent: output data size estimator
127   void GetOutputDataSize( unsigned long& constBase, double& inputMultiplier );
128
129   /// inherited from AliHLTComponent: spawn function.
130   virtual AliHLTComponent* Spawn();
131
132   /// inherited from AliHLTComponent: list of OCDB objects
133   void GetOCDBObjectDescription(TMap* const targetMap);
134
135   struct AliHLTTPCTrackModelBlock {
136     AliHLTUInt8_t  fVersion;             //! version of the header
137     AliHLTUInt8_t  fDeflaterMode;        //! deflater mode
138     AliHLTUInt16_t fTrackCount;          //! number of tracks in the block
139     AliHLTUInt16_t fClusterCount;        //! number of clusters in the block
140     AliHLTUInt16_t fGlobalParameterCnt;  //! number of global parameters
141     float          fGlobalParameters[1]; //! array of global parameters
142   };
143
144 protected:
145   /// inherited from AliHLTProcessor: data processing
146   int DoEvent( const AliHLTComponentEventData& evtData, 
147                const AliHLTComponentBlockData* blocks, 
148                AliHLTComponentTriggerData& trigData,
149                AliHLTUInt8_t* outputPtr, 
150                AliHLTUInt32_t& size,
151                AliHLTComponentBlockDataList& outputBlocks );
152   using AliHLTProcessor::DoEvent;
153
154   /// inherited from AliHLTComponent: component initialisation and argument scan.
155   int DoInit( int argc, const char** argv );
156
157   /// inherited from AliHLTComponent: component cleanup
158   int DoDeinit();
159
160   /// inherited from AliHLTComponent: argument scan
161   int ScanConfigurationArgument(int argc, const char** argv);
162
163   int ProcessTrackClusters(AliHLTGlobalBarrelTrack* pTracks, unsigned nofTracks,
164                            AliHLTTrackGeometry::AliHLTTrackGrid* pTrackIndex,
165                            const vector<int>& trackIndexMap,
166                            AliHLTSpacePointContainer::AliHLTSpacePointPropertyGrid* pClusterIndex,
167                            AliHLTSpacePointContainer* pClusters,
168                            int slice, int partition) const;
169
170   int ProcessRemainingClusters(AliHLTGlobalBarrelTrack* pTracks, unsigned nofTracks,
171                                AliHLTTrackGeometry::AliHLTTrackGrid* pTrackIndex,
172                                const vector<int>& trackIndexMap,
173                                AliHLTSpacePointContainer::AliHLTSpacePointPropertyGrid* pClusterIndex,
174                                AliHLTSpacePointContainer* pClusters,
175                                int slice, int partition) const;
176
177   int FindCellClusters(int trackId, int padrow, float pad, float time,
178                        AliHLTSpacePointContainer::AliHLTSpacePointPropertyGrid* pClusterIndex,
179                        AliHLTSpacePointContainer* pClusters,
180                        AliHLTTrackGeometry::AliHLTTrackPoint* pTrackPoint,
181                        AliHLTUInt32_t clusterId=~(AliHLTUInt32_t)0) const;
182
183   int WriteTrackClusters(const vector<AliHLTGlobalBarrelTrack>& tracks,
184                          AliHLTSpacePointContainer* pSpacePoints,
185                          AliHLTDataDeflater* pDeflater,
186                          AliHLTUInt8_t* outputPtr,
187                          AliHLTUInt32_t capacity) const;
188
189 private:
190   AliHLTTPCDataCompressionComponent(const AliHLTTPCDataCompressionComponent&);
191   AliHLTTPCDataCompressionComponent& operator=(const AliHLTTPCDataCompressionComponent&);
192
193   int InitDeflater(int mode);
194
195   /// calculate correction factor and offset for a linear approximation of the
196   /// drift time transformation, separately for A and C side
197   int InitDriftTimeTransformation();
198   /// calculate correction factor and offset for a linear approximation of the
199   /// drift time transformation by just probing the range of timebins
200   int CalculateDriftTimeTransformation(AliHLTTPCClusterTransformation& transform, int slice, int padrow,
201                                        float& m, float& n) const;
202
203   AliHLTComponentBenchmark* GetBenchmarkInstance() const {return fpBenchmark;}
204
205   int fMode; //! mode
206   int fDeflaterMode; //! deflater mode
207   int fVerificationMode; //! mode for verification and unit tests
208
209   float fMaxDeltaPad; //! maximum deviation in pad
210   float fMaxDeltaTime; //! maximum deviation in time
211
212   /// input raw cluster handler
213   AliHLTSpacePointContainer* fRawInputClusters; //! input raw cluster handler
214   /// input cluster handler
215   AliHLTSpacePointContainer* fInputClusters; //! input cluster handler
216
217   /// index grid for tracks store track id for padrow crossings
218   AliHLTTrackGeometry::AliHLTTrackGrid* fTrackGrid; //! index grid for tracks
219
220   /// index grid for clusters
221   AliHLTSpacePointContainer::AliHLTSpacePointPropertyGrid* fSpacePointGrid; //! index grid for clusters
222
223   /// deflater
224   AliHLTDataDeflater* fpDataDeflater; //! deflater for raw clusters
225
226   /// compression factor histogram
227   TH1F* fHistoCompFactor; //! histogram of compression factor
228   TH1F* fHistoResidualPad; //! histogram for pad residual
229   TH1F* fHistoResidualTime; //! histogram for time residual
230   TH1F* fHistoClustersOnTracks; //! clusters on tracks for track model compression
231   TH1F* fHistoClusterRatio; //! fraction of clusters assigned to the track model compression
232   TH1F* fHistoTrackClusterRatio; //! fraction of track clusters assigned to the track model compression
233   TString fHistogramFile; //! file to save histogram
234   TString fTrainingTableOutput; //! output file for huffman tables in training mode
235
236   /// benchmark
237   AliHLTComponentBenchmark* fpBenchmark; //! benchmark instance
238
239   /// temporary array of ids of associated cluster ids
240   vector<AliHLTUInt32_t>* fpWrittenAssociatedClusterIds; //!
241
242   float fDriftTimeFactorA; //! drift time A side
243   float fDriftTimeOffsetA; //! drift time A side
244   float fDriftTimeFactorC; //! drift time C side
245   float fDriftTimeOffsetC; //! drift time C side
246
247   /// verbosity
248   int fVerbosity; // verbosity for debug printout
249
250   ClassDef(AliHLTTPCDataCompressionComponent, 0)
251 };
252
253 #endif //ALIHLTTPCDATACOMPRESSIONCOMPONENT_H