- Put the code to fill ESD with trigger data back in the correct framework:
[u/mrichter/AliRoot.git] / MUON / READMErec.txt
1 // $Id$
2
3 /*! 
4
5 \page README_rec Reconstruction
6  
7 The reconstruction is a multistage process, driven by the AliMUONTracker and AliMUONReconstructor classes
8 via the AliReconstruction class, which is divided into three parts:
9 - the digitization of the electronic response,
10 - the clustering of the digits to locate the crossing point of the muon with the chamber,
11 - the tracking to reconstruct the trajectory of the muon in the spectrometer from which we can extract the kinematics.
12
13 All the adjustable options and parameters used to tune the different part of the reconstruction are handled by the class AliMUONRecoParam.
14
15
16 \section rec_s1 Digitization
17
18 - We read the RAW data, convert them (convert them back for simulated data) to digit (object inheriting from AliMUONVDigit
19 stored into containers inheriting from AliMUONVDigitStore). This conversion is performed by the class AliMUONDigitMaker.
20 - We calibrate the digits, via AliMUONDigitCalibrator, by subtracting pedestals and multiplying by gains. All the calibration parameters
21 (pedestals, gains, capacitances and HV) are read from the OCDB and stored into AliMUONCalibrationData objects.
22 - We create the status of the digit (e.g. pedestal higher than maximum or HV switched off), using AliMUONPadStatusMaker.
23 - We create the status map for each digit, i.e the global status (good/bad) of that digit and of its neighbords, using AliMUONPadStatusMapMaker.
24 - Calibrated digits might be saved (back) to TreeD in MUON.Digits.root file.
25
26
27 \section rec_s2 Clustering
28
29 - We convert the digits having a positive charge into pads (AliMUONPad objects), which also contain information about the digit geometrical
30 position.
31 - We loop over pads in the bending and non-bending planes of the DE to form groups of contiguous pads. We then merge the overlapping groups
32 of pads from both cathodes to build the pre-clusters that are the objects to be clusterized.
33 - We unfold each pre-cluster in order to extract the number and the position of individual clusters merged in it (complex pre-clusters are
34 made of a superimposition of signals from muon from physical background (e.g. hadrons) and from electronic noise).
35
36 Several versions of pre-clustering are available, all inheriting from AliMUONVClusterFinder, with different ways to loop over pads to form
37 pre-clusters:
38 - AliMUONPreClusterFinder
39 - AliMUONPreClusterFinderV2
40 - AliMUONPreClusterFinderV3
41
42 Several version of clustering are available, all inheriting from AliMUONVClusterFinder, with different degrees of complexity:
43 - AliMUONClusterFinderCOG simply compute the Center Of Gravity of the charge distribution in the pre-cluster.
44 - AliMUONClusterFinderSimpleFit simply fit the charge distribution with a single 2D Mathieson function.
45 - AliMUONClusterFinderMLEM uses the Maximum Likelihood Expectation Minimization algorithm.
46 This is a recursive procedure which determines the number and the approximate position of clusters into the pre-cluster that are needed
47 to reproduce the whole charge distribution. It assumes that the charge distribution of each single cluster follow a 2D Mathieson function.
48 If the estimated number of clusters is too high (>3), the pre-cluster is split into several groups of 1-2 or 3 clusters selected having
49 the minimum total coupling to all the other clusters into the pre-cluster. Each group of clusters is then fitted with a sum of 2D Mathieson
50 functions to extract their exact position.
51 - AliMUONClusterFinderPeakCOG is a simplified version of the MLEM clusterizer, without splitting and computing the Center Of Gravity of the
52 local charge distribution to extract the position of every clusters found in the pre-cluster.
53 - AliMUONClusterFinderPeakFit is another simplified version of the MLEM clusterizer again without splitting. The pre-cluster is fitted with
54 a sum of 2D Mathieson if it contains less than 3 clusters or we switch to the above COG method.
55
56 The cluster recontruction is driven by the class AliMUONSimpleClusterServer, inheriting from AliMUONVClusterServer.
57 It can be performed either before or during the tracking. In the first case, all the chambers are fully clusterized and the clusters (objects
58 inheriting from AliMUONVCluster stored into containers inheriting from AliMUONVClusterStore) are saved to TreeR in Muon.RecPoints.root file.
59 We use the class AliMUONLegacyClusterServer (also inheriting from AliMUONVClusterServer) read back the TreeR and provide clusters to the tracking.
60 In the second case, we clusterize the chambers only in the region where we are looking for new clusters to be attached to the track candidates.
61 This makes the clustering faster but the clusters cannot be saved to the TreeR.
62
63
64 \section rec_s3 Tracking
65
66 The MUON code provides two different algorithms to reconstruct the muon trajectory. In both cases the general tracking procedure is the same,
67 the only difference being the way the track parameters are computed from the cluster positions. The "Original" algorithm perform a fit of the
68 track parameters using the MINUIT package of Root, while the "Kalman" algorithm compute them using analytical formulae. The classes driving
69 the tracking are AliMUONTrackReconstructor and AliMUONTrackReconstructorK for the "Original" and the "Kalman" algorithms respectively,
70 both inheriting from AliMUONVTrackReconstructor. The reconstructed muon tracks are objects of the class AliMUONTrack.
71
72 The general tracking procedure is as follow:
73 - Build primary track candidates using clusters on station 4 and 5: Make all combination of clusters between the two chambers of station 5(4).
74 For each combination compute the local position and orientation of the track and estimate its bending momentum given the averaged magnetic field
75 inside the dipole and assuming that the track is coming from the vertex. Then select pairs for which the estimated bending momentum and the
76 non-bending slope are within given limits. Extrapolate the primary track candidates to station 4(5), look for at least one compatible cluster to
77 validate them and recompute the track parameters.
78 - Remove the identical track candidates, i.e. the ones sharing exactly the same clusters.
79 - Propagate the track to station 3, 2 then 1 and, at each step, ask the "ClusterServer" to provide clusters in the region of interest,
80 and select the one(s) compatible with the track. The track is validated if we find at least 1 cluster per station.
81 - Remove the double tracks, i.e. the ones sharing more than half of their clusters, keeping the one with the larger number of cluster or the
82 one with the lowest chi2 in case of equality. Then recompute the track parameters at each attached cluster (using the so called Smoother algorithm
83 in the case of the "Kalman" tracking).
84 - The reconstructed tracks are finally matched with the trigger tracks (reconstructed from the local response of the trigger) to identify the
85 muon(s) that made the trigger.
86
87 The new clusters to be attached to the track are selected according to their local chi2 (i.e. their transverse position relatively to the track,
88 normalized by the convolution of the cluster resolution with the resolution of track extrapolated at the cluster location).
89 If several compatible clusters are foundon the same chamber, the track candidate is duplicated to consider all the possibilities.
90
91 The last part of the tracking is the extrapolation of the reconstructed tracks to the vertex of the collision. The vertex position is measured
92 by the SPD (the Silicon Pixel layers of the ITS Detector). In order to be able to perform any kind of muon analysis, we need to compute the track
93 parameters assuming the muon has been produced in the initial collision as well as the track parameters in the vertex plane. The first set of
94 parameters is obtained by correcting for energy loss and multiple Coulomb scattering in the front absorber (we force the track to come from the
95 exact vertex position (x,y,z) by using the Branson correction), while the second one is obtained by correcting for energy loss only.
96
97 The final results of the reconstruction - from which we will perform the physical analyses, compute detector efficiencies and perform calibration
98 checks - are stored in objects of the class AliESDMuonTrack and saved in AliESD.root file. Three kinds of track can be saved: a tracker track
99 matched with a trigger track, a tracker track alone and a trigger track alone (unused data members are set to default in the last two cases).
100 The complete list of MUON data saved into ESD is given in section @ref rec_s5.
101
102
103 \section rec_s4 How to tune the muon reconstruction
104
105 Several options and adjustable parameters allow to tune the entire reconstruction. These can be changed by adding the following lines in the
106 reconstruction macro (runReconstruction.C):
107 \verbatim
108   AliMUONRecoParam *muonRecoParam = AliMUONRecoParam::Get...Param();
109   muonRecoParam->Use...();
110   muonRecoParam->Set...();
111   ...
112   AliRecoParam::Instance()->RegisterRecoParam(muonRecoParam);
113 \endverbatim
114
115 Three sets of default parameters are available:
116 - <code>GetLowFluxParam()</code>: parameters for p-p collisions
117 - <code>GetHighFluxParam()</code>: parameters for Pb-Pb collisions
118 - <code>GetCosmicParam()</code>: parameters for cosmic runs
119
120 Every option/parameter can also be set one by one. Here is the complete list of available setters:
121 - <code>SetCalibrationMode("mode")</code>: set the calibration mode: NOGAIN (only do pedestal subtraction),
122   GAIN (do pedestal subtraction and apply gain correction, but with a single capacitance value for all channels),
123   GAINCONSTANTCAPA (as GAIN, but with a channel-dependent capacitance value).
124 - <code>SetClusteringMode("mode")</code>: set the clustering (pre-clustering) mode: NOCLUSTERING, PRECLUSTER, PRECLUSTERV2, PRECLUSTERV3, COG,
125   SIMPLEFIT, SIMPLEFITV3, MLEM:DRAW, MLEM, MLEMV2, MLEMV3.
126 - <code>SetTrackingMode("mode")</code>: Set the tracking mode: ORIGINAL, KALMAN.
127 - <code>CombineClusterTrackReco(flag)</code>: switch on/off the combined cluster/track reconstruction
128 - <code>SaveFullClusterInESD(flag, % of event)</code>: save all cluster info (including pads) in ESD, for the given percentage of events
129   (100% by default)
130 - <code>SetMostProbBendingMomentum(value)</code>: set the most probable value (GeV/c) of momentum in bending plane (used when B=0)
131 - <code>SetMinBendingMomentum(value)</code>: set the minimum acceptable value (GeV/c) of track momentum in bending plane
132 - <code>SetMaxBendingMomentum(value)</code>: set the maximum acceptable value (GeV/c) of track momentum in bending plane
133 - <code>SetMaxNonBendingSlope(value)</code>: set the maximum value of the track slope in non bending plane
134 - <code>SetMaxBendingSlope(value)</code>: set the maximum value of the track slope in non bending plane (used when B=0)
135 - <code>SetNonBendingVertexDispersion(value)</code>: set the vertex dispersion (cm) in non bending plane (used for original tracking only)
136 - <code>SetBendingVertexDispersion(value)</code>: set the vertex dispersion (cm) in bending plane (used for original tracking only)
137 - <code>SetMaxNonBendingDistanceToTrack(value)</code>: set the maximum distance to the track to search for compatible cluster(s) in non bending
138   direction. This value is convoluted with the track resolution to define the region of interest.
139 - <code>SetMaxBendingDistanceToTrack(value)</code>: set the maximum distance to the track to search for compatible cluster(s) in bending direction
140   This value is convoluted with the track resolution to define the region of interest.
141 - <code>SetSigmaCutForTracking(value)</code>: set the cut in sigma to apply on cluster (local chi2) and track (global chi2) during tracking
142 - <code>ImproveTracks(flag, sigma cut)</code>: recompute the local chi2 of each cluster with the final track parameters and removed the ones that
143   do not pass a new quality cut. The track is removed if we do not end with at least one good cluster per station.
144 - <code>ImproveTracks(flag)</code>: same as above using the default quality cut
145 - <code>SetSigmaCutForTrigger(value)</code>: set the cut in sigma to apply on track during trigger hit pattern search
146 - <code>SetStripCutForTrigger(value)</code>: set the cut in strips to apply on trigger track during trigger chamber efficiency
147 - <code>SetMaxStripAreaForTrigger(value)</code>: set the maximum search area in strips to apply on trigger track during trigger chamber efficiency
148 - <code>SetMaxNormChi2MatchTrigger(value)</code>: set the maximum normalized chi2 for tracker/trigger track matching
149 - <code>TrackAllTracks(flag)</code>: consider all the clusters passing the sigma cut (duplicate the track) or only the best one
150 - <code>RecoverTracks(flag)</code>: if no cluster is found in a given station, we try it again after having removed the worst of the 2 clusters
151   attached in the previous station (assuming it was a cluster from background).
152 - <code>MakeTrackCandidatesFast(flag)</code>: make the primary track candidates formed by cluster on stations 4 and 5 assuming there is no
153   magnetic field in that region to speed up the reconstruction.
154 - <code>MakeMoreTrackCandidates(Bool_t flag)</code>: make the primary track candidate using 1 cluster on station 4 and 1 cluster on station 5
155   instead of starting from 2 clusters in the same station.
156 - <code>ComplementTracks(Bool_t flag)</code>: look for potentially missing cluster to be attached to the track (a track may contain up to 2
157   clusters per chamber do to the superimposition of DE, while the tracking procedure is done in such a way that only 1 can be attached).
158 - <code>UseSmoother(Bool_t flag)</code>: use or not the smoother to recompute the track parameters at each attached cluster
159   (used for Kalman tracking only)
160 - <code>UseChamber(Int_t iCh, Bool_t flag)</code>: set the chambers to be used (disable the clustering if the chamber is not used).
161 - <code>RequestStation(Int_t iSt, Bool_t flag)</code>: impose/release the condition "at least 1 cluster per station" for that station.
162 - <code>BypassSt45(Bool_t value)</code>: make the primary track candidate from the trigger track instead of using station 4 and 5.
163
164 We can use the method Print("FULL") to printout all the parameters and options set in the class AliMUONRecoParam.
165
166
167 \section rec_s5 ESD content
168
169 The final results of the reconstruction are stored in objects of the class AliESDMuonTrack. Those objects contain:
170 - Tracker track parameters (x, theta_x, y, theta_y, 1/p_yz) at vertex (x=x_vtx; y=y_vtx)
171 - Tracker track parameters in the vertex plane
172 - Tracker track parameters at first cluster
173 - Tracker track parameter covariances at first cluster
174 - Tracker track global informations (chi2, number of clusters, cluster map)
175 - TClonesArray of associated clusters stored in AliESDMuonCluster objects
176 - Trigger track informations (local trigger decision, strip pattern, hit pattern)
177 - Chi2 of tracker/trigger track matching
178
179 Each AliESDMuonCluster object contain by default:
180 - Cluster ID providing information about the location of the cluster (chamber ID and DE ID)
181 - Cluster position (x,y,z)
182 - Cluster resolution (sigma_x,sigma_y)
183
184 More information about clusters can be stored in these objects for a given fraction of events:
185 - Charge
186 - Chi2
187 - TClonesArray of associated pads stored in AliESDMuonPad objects
188
189 Each AliESDMuonPad object contain:
190 - Digit ID providing information about the location of the digit (DE ID, Manu ID, Manu channel and cathode)
191 - Raw charge (ADC value)
192 - Calibrated charge
193
194
195 \section rec_s6 Conversion between MUON/ESD objects
196
197 Every conversion between MUON objects (AliMUOVDigit/AliMUONVCluster/AliMUONTrack) and ESD objects
198 (AliESDMuonPad/AliESDMuonCluster/AliESDMuonTrack) is done by the class AliMUONESDInterface. There are 2 ways of using this class:
199
200 1) Using the static methods to convert the objects one by one (and possibly put them into the provided store):
201 - Get track parameters at vertex, at DCA, ...:
202 \verbatim
203   ...
204   AliESDMuonTrack* esdTrack = new AliESDMuonTrack(*(esd->GetMuonTrack(iTrack)));
205   AliMUONTrackParam param;
206   AliMUONESDInterface::GetParamAtVertex(*esdTrack, param);
207 \endverbatim
208   
209 - Convert an AliMUONVDigit to an AliESDMuonPad:
210 \verbatim
211   ...
212   AliMUONVDigit *digit = ...;
213   AliESDMuonPad esdPad;
214   AliMUONESDInterface::MUONToESD(*digit, esdPad);
215 \endverbatim
216   
217 - Convert an AliMUONLocalTrigger to a ghost AliESDMuonTrack (containing only trigger informations):
218 \verbatim
219   ...
220   AliMUONLocalTrigger* locTrg = ...;
221   AliESDMuonTrack esdTrack;
222   AliMUONESDInterface::MUONToESD(locTrg, esdTrack, trackId);
223 \endverbatim
224
225 - Convert an AliESDMuonTrack to an AliMUONTrack:
226 \verbatim
227   ...
228   AliESDMuonTrack* esdTrack = new AliESDMuonTrack(*(esd->GetMuonTrack(iTrack)));
229   AliMUONTrack track;
230   AliMUONESDInterface::ESDToMUON(*esdTrack, track);
231 \endverbatim
232   
233 - Add an AliESDMuonTrack into an AliMUONVTrackStore:
234 \verbatim
235   ...
236   AliESDMuonTrack* esdTrack = new AliESDMuonTrack(*(esd->GetMuonTrack(iTrack)));
237   AliMUONVTrackStore *trackStore = AliMUONESDInteface::NewTrackStore();
238   AliMUONESDInterface::Add(*esdTrack, *trackStore);
239 \endverbatim
240
241 2) Loading an entire ESDEvent and using the finders and/or the iterators to access the corresponding MUON objects:
242 - First load the ESD event:
243 \verbatim
244   AliMUONESDInterface esdInterface;
245   esdInterface.LoadEvent(*esd);
246 \endverbatim
247   
248 - Get the track store:
249 \verbatim
250   AliMUONVTrackStore* trackStore = esdInterface.GetTracks();
251 \endverbatim
252   
253 - Access the number of digits in a particular cluster:
254 \verbatim
255   Int_t nDigits = esdInterface.GetNDigitsInCluster(clusterId);
256 \endverbatim
257   
258 - Find a particular digit using its ID:
259 \verbatim
260   AliMUONVDigit *digit = esdInterface.FindDigit(digitId);
261 \endverbatim
262
263 - Find a particular cluster in a given track using their IDs:
264 \verbatim
265   AliMUONVCluster* cluster = esdInterface.FindCluster(trackId, clusterId);
266 \endverbatim
267   
268 - Iterate over all clusters of a particular track using an iterator:
269 \verbatim
270   TIterator* nextCluster = esdInterface.CreateClusterIterator(trackId);
271   while ((cluster = static_cast<AliMUONVCluster*>(nextCluster()))) {...}
272 \endverbatim
273
274 Note: You can change (via static method) the type of the store this class is using:
275 \verbatim
276   AliMUONESDInterface::UseTrackStore("name");
277   AliMUONESDInterface::UseClusterStore("name");
278   AliMUONESDInterface::UseDigitStore("name");
279   AliMUONESDInterface::UseTriggerStore("name");
280 \endverbatim
281
282
283 \section rec_s7 ESD cluster/track refitting
284
285 We can re-clusterize and re-track the clusters/tracks stored into the ESD by using the class AliMUONRefitter. This class gets the MUON objects
286 to be refitted from an instance of AliMUONESDInterface (see section @ref rec_s6), then uses the reconstruction framework to refit the
287 objects. The reconstruction parameters are still set via the class AliMUONRecoParam (see section @ref rec_s5). The initial data are not changed.
288 Results are stored into new MUON objects. The aim of the refitting is to be able to study effects of changing the reconstruction parameters or the
289 calibration parameters without re-running the entire reconstruction.
290
291 To use this class we first have to connect it to the ESD interface containing MUON objects:
292 \verbatim
293   AliMUONRefitter refitter;
294   refitter.Connect(&esdInterface);
295 \endverbatim
296
297 We can then:
298 - Re-clusterize the ESD clusters using the attached ESD pads (several new clusters can be reconstructed per ESD cluster):
299 \verbatim
300   AliMUONVClusterStore* clusterStore = refitter.ReClusterize(iTrack, iCluster);
301   AliMUONVClusterStore* clusterStore = refitter.ReClusterize(clusterId);
302 \endverbatim
303   
304 - Re-fit the ESD tracks using the attached ESD clusters:
305 \verbatim
306   AliMUONTrack* track = refitter.RetrackFromClusters(iTrack);
307   AliMUONVTrackStore* trackStore = refitter.ReconstructFromClusters();
308 \endverbatim
309   
310 - Reconstruct the ESD tracks from ESD pads (i.e. re-clusterize the attached clusters). Consider all the combination of clusters and return only
311   the best one:
312 \verbatim
313   AliMUONTrack* track = refitter.RetrackFromDigits(iTrack);
314   AliMUONVTrackStore* trackStore = refitter.ReconstructFromDigits();
315 \endverbatim
316
317 The macro MUONRefit.C is an example of using this class. The results are stored in a new AliESDs.root file.
318
319
320 This chapter is defined in the READMErec.txt file.
321
322 */