Separating run-dependent mapping data from data, which are not
[u/mrichter/AliRoot.git] / MUON / READMErec.txt
CommitLineData
91509ec6 1// $Id$
2
3/*!
4
5\page README_rec Reconstruction
6
b1fea02e 7The reconstruction is a multistage process, driven by the AliMUONTracker and AliMUONReconstructor classes
8via 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.
91509ec6 12
b1fea02e 13All the adjustable options and parameters used to tune the different part of the reconstruction are handled by the class AliMUONRecoParam.
91509ec6 14
91509ec6 15
b1fea02e 16\section rec_s1 Digitization
91509ec6 17
b1fea02e 18- We read the RAW data, convert them (convert them back for simulated data) to digit (object inheriting from AliMUONVDigit
19stored 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.
fd3ef136 25
fd3ef136 26
b1fea02e 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
30position.
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
32of 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
34made of a superimposition of signals from muon from physical background (e.g. hadrons) and from electronic noise).
35
36Several versions of pre-clustering are available, all inheriting from AliMUONVClusterFinder, with different ways to loop over pads to form
37pre-clusters:
38- AliMUONPreClusterFinder
39- AliMUONPreClusterFinderV2
40- AliMUONPreClusterFinderV3
41
42Several 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.
46This is a recursive procedure which determines the number and the approximate position of clusters into the pre-cluster that are needed
47to reproduce the whole charge distribution. It assumes that the charge distribution of each single cluster follow a 2D Mathieson function.
48If 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
49the 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
50functions 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
52local 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
54a sum of 2D Mathieson if it contains less than 3 clusters or we switch to the above COG method.
55
56The cluster recontruction is driven by the class AliMUONSimpleClusterServer, inheriting from AliMUONVClusterServer.
57It can be performed either before or during the tracking. In the first case, all the chambers are fully clusterized and the clusters (objects
58inheriting from AliMUONVCluster stored into containers inheriting from AliMUONVClusterStore) are saved to TreeR in Muon.RecPoints.root file.
59We use the class AliMUONLegacyClusterServer (also inheriting from AliMUONVClusterServer) read back the TreeR and provide clusters to the tracking.
60In 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.
61This makes the clustering faster but the clusters cannot be saved to the TreeR.
62
63
64\section rec_s3 Tracking
65
66The MUON code provides two different algorithms to reconstruct the muon trajectory. In both cases the general tracking procedure is the same,
67the only difference being the way the track parameters are computed from the cluster positions. The "Original" algorithm perform a fit of the
68track parameters using the MINUIT package of Root, while the "Kalman" algorithm compute them using analytical formulae. The classes driving
69the tracking are AliMUONTrackReconstructor and AliMUONTrackReconstructorK for the "Original" and the "Kalman" algorithms respectively,
70both inheriting from AliMUONVTrackReconstructor. The reconstructed muon tracks are objects of the class AliMUONTrack.
71
72The 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).
74For each combination compute the local position and orientation of the track and estimate its bending momentum given the averaged magnetic field
75inside the dipole and assuming that the track is coming from the vertex. Then select pairs for which the estimated bending momentum and the
76non-bending slope are within given limits. Extrapolate the primary track candidates to station 4(5), look for at least one compatible cluster to
77validate 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,
80and 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
82one with the lowest chi2 in case of equality. Then recompute the track parameters at each attached cluster (using the so called Smoother algorithm
83in 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
85muon(s) that made the trigger.
86
87The new clusters to be attached to the track are selected according to their local chi2 (i.e. their transverse position relatively to the track,
88normalized by the convolution of the cluster resolution with the resolution of track extrapolated at the cluster location).
89If several compatible clusters are foundon the same chamber, the track candidate is duplicated to consider all the possibilities.
90
91The last part of the tracking is the extrapolation of the reconstructed tracks to the vertex of the collision. The vertex position is measured
92by 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
93parameters assuming the muon has been produced in the initial collision as well as the track parameters in the vertex plane. The first set of
94parameters is obtained by correcting for energy loss and multiple Coulomb scattering in the front absorber (we force the track to come from the
95exact vertex position (x,y,z) by using the Branson correction), while the second one is obtained by correcting for energy loss only.
96
97The final results of the reconstruction - from which we will perform the physical analyses, compute detector efficiencies and perform calibration
98checks - are stored in objects of the class AliESDMuonTrack and saved in AliESD.root file. Three kinds of track can be saved: a tracker track
99matched 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).
100The 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
105Several options and adjustable parameters allow to tune the entire reconstruction. These can be changed by adding the following lines in the
106reconstruction macro (runReconstruction.C):
107\verbatim
108 AliMUONRecoParam *muonRecoParam = AliMUONRecoParam::Get...Param();
fd3ef136 109 muonRecoParam->Use...();
110 muonRecoParam->Set...();
111 ...
112 AliRecoParam::Instance()->RegisterRecoParam(muonRecoParam);
b1fea02e 113\endverbatim
114
115Three 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
120Every 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.
de487b6e 162- <code>BypassSt45(Bool_t st4, Bool_t st5)</code>: make the primary track candidate from the trigger track instead of using stations 4 and/or 5.
b1fea02e 163
164We 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
169The 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
179Each 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
184More 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
189Each 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
197Every 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
2001) 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
2412) 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
274Note: 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
285We can re-clusterize and re-track the clusters/tracks stored into the ESD by using the class AliMUONRefitter. This class gets the MUON objects
286to be refitted from an instance of AliMUONESDInterface (see section @ref rec_s6), then uses the reconstruction framework to refit the
287objects. The reconstruction parameters are still set via the class AliMUONRecoParam (see section @ref rec_s5). The initial data are not changed.
288Results 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
289calibration parameters without re-running the entire reconstruction.
fd3ef136 290
b1fea02e 291To 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
fd3ef136 296
b1fea02e 297We 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
fd3ef136 316
b1fea02e 317The macro MUONRefit.C is an example of using this class. The results are stored in a new AliESDs.root file.
fd3ef136 318
91509ec6 319
aa36dc36 320This chapter is defined in the READMErec.txt file.
91509ec6 321
322*/