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 stations 3, 2 then 1. At each station, ask the "ClusterServer" to provide clusters in the region of interest defined in
  80 the reconstruction parameters. Select the one(s) compatible with the track and recompute the track parameters, or remove the track if no good
  81 cluster is found.
  82 - Remove the connected tracks (i.e. the ones sharing one cluster or more in stations 3, 4 or 5) keeping the one with the largest number of cluster
  83 or the one with the lowest chi2 in case of equality. Then recompute the track parameters at each attached cluster (using the so-called Smoother
  84 algorithm in the case of the "Kalman" tracking).
  85 - The reconstructed tracks are finally matched with the trigger tracks (reconstructed from the local response of the trigger) to identify the
  86 muon(s) that made the trigger.
  87
  88 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,
  89 normalized by the convolution of the cluster resolution with the resolution of track extrapolated at the cluster location).
  90 If several compatible clusters are found on the same chamber, the track candidate is duplicated to consider all the possibilities.
  91
  92 The last part of the tracking is the extrapolation of the reconstructed tracks to the vertex of the collision. The vertex position is measured
  93 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
  94 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
  95 parameters is obtained by correcting for energy loss and multiple Coulomb scattering in the front absorber (we force the track to come from the
  96 exact vertex position (x,y,z) by using the Branson correction), while the second one is obtained by correcting for energy loss only.
  97
  98 The final results of the reconstruction - from which we will perform the physical analyses, compute detector efficiencies and perform calibration
  99 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
 100 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).
 101 The complete list of MUON data saved into ESD is given in section @ref rec_s5.
 102
 103
 104 \section rec_s4 How to tune the muon reconstruction
 105
 106 Several options and adjustable parameters allow to tune the entire reconstruction. They are stored in the OCDB in the directory MUON/Calib/RecoParam.
 107 However, it is possible to customize the parameters by adding the following lines in the reconstruction macro (runReconstruction.C):
 108 \verbatim
 109   AliMUONRecoParam *muonRecoParam = AliMUONRecoParam::Get...Param();
 110   muonRecoParam->Use...();
 111   muonRecoParam->Set...();
 112   ...
 113   MuonRec->SetRecoParam("MUON",muonRecoParam);
 114 \endverbatim
 115
 116 Three sets of default parameters are available:
 117 - <code>GetLowFluxParam()</code>: parameters for p-p collisions
 118 - <code>GetHighFluxParam()</code>: parameters for Pb-Pb collisions
 119 - <code>GetCosmicParam()</code>: parameters for cosmic runs
 120
 121 Every option/parameter can be set one by one. Here is the complete list of available setters:
 122 - <code>SetCalibrationMode("mode")</code>: set the calibration mode: NOGAIN (only do pedestal subtraction),
 123   GAIN (do pedestal subtraction and apply gain correction, but with a single capacitance value for all channels),
 124   GAINCONSTANTCAPA (as GAIN, but with a channel-dependent capacitance value).
 125 - <code>SetClusteringMode("mode")</code>: set the clustering (pre-clustering) mode: NOCLUSTERING, PRECLUSTER, PRECLUSTERV2, PRECLUSTERV3, COG,
 126   SIMPLEFIT, SIMPLEFITV3, MLEM:DRAW, MLEM, MLEMV2, MLEMV3.
 127 - <code>SetTrackingMode("mode")</code>: Set the tracking mode: ORIGINAL, KALMAN.
 128 - <code>CombineClusterTrackReco(flag)</code>: switch on/off the combined cluster/track reconstruction
 129 - <code>SaveFullClusterInESD(flag, % of event)</code>: save all cluster info (including pads) in ESD, for the given percentage of events
 130   (100% by default)
 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>RemoveConnectedTracksInSt12(Bool_t flag)</code>: extend the definition of connected tracks to be removed at the end of the tracking
 159 procedure to the ones sharing one cluster on more in any station, including stations 1 and 2.
 160 - <code>UseSmoother(Bool_t flag)</code>: use or not the smoother to recompute the track parameters at each attached cluster
 161   (used for Kalman tracking only)
 162 - <code>UseChamber(Int_t iCh, Bool_t flag)</code>: set the chambers to be used (disable the clustering if the chamber is not used).
 163 - <code>RequestStation(Int_t iSt, Bool_t flag)</code>: impose/release the condition "at least 1 cluster per station" for that station.
 164 - <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.
 165 - <code>SetHVSt12Limits(float low, float high)</code>: Set Low and High threshold for St12 HV
 166 - <code>SetHVSt345Limits(float low, float high)</code>: Set Low and High threshold for St345 HV
 167 - <code>SetPedMeanLimits(float low, float high)</code>: Set Low and High threshold for pedestal mean
 168 - <code>SetPedSigmaLimits(float low, float high)</code>: Set Low and High threshold for pedestal sigma
 169 - <code>SetGainA1Limits(float low, float high)</code>: Set Low and High threshold for gain a0 term
 170 - <code>SetGainA2Limits(float low, float high)</code>: Set Low and High threshold for gain a1 term
 171 - <code>SetGainThresLimits(float low, float high)</code>: Set Low and High threshold for gain threshold term
 172 - <code>SetPadGoodnessMask(UInt_t mask)</code>: Set the goodness mask (see AliMUONPadStatusMapMaker)
 173 - <code>ChargeSigmaCut(Double_t value)</code>: Number of sigma cut we must apply when cutting on adc-ped
 174 - <code>SetDefaultNonBendingReso(Int_t iCh, Double_t val)</code>: Set the default non bending resolution of chamber iCh
 175 - <code>SetDefaultBendingReso(Int_t iCh, Double_t val)</code>: Set the default bending resolution of chamber iCh
 176
 177 We can use the method Print("FULL") to printout all the parameters and options set in the class AliMUONRecoParam.
 178
 179
 180 \section rec_s5 ESD content
 181
 182 Three kinds of track can be saved in ESD: a tracker track matched with a trigger track, a tracker track alone and a trigger track alone (unused
 183 data members are set to default values in the last two cases). These tracks are stored in objects of the class AliESDMuonTrack. Those objects
 184 contain:
 185 - Tracker track parameters (x, theta_x, y, theta_y, 1/p_yz) at vertex (x=x_vtx; y=y_vtx)
 186 - Tracker track parameters in the vertex plane
 187 - Tracker track parameters at first cluster
 188 - Tracker track parameter covariances at first cluster
 189 - Tracker track global informations (chi2, number of clusters, cluster map)
 190 - TClonesArray of associated clusters stored in AliESDMuonCluster objects
 191 - Trigger track informations (local trigger decision, strip pattern, hit pattern)
 192 - Chi2 of tracker/trigger track matching
 193
 194 Each AliESDMuonCluster object contain by default:
 195 - Cluster ID providing information about the location of the cluster (chamber ID and DE ID)
 196 - Cluster position (x,y,z)
 197 - Cluster resolution (sigma_x,sigma_y)
 198
 199 More information about clusters can be stored in these objects for a given fraction of events:
 200 - Charge
 201 - Chi2
 202 - TClonesArray of associated pads stored in AliESDMuonPad objects
 203
 204 Each AliESDMuonPad object contain:
 205 - Digit ID providing information about the location of the digit (DE ID, Manu ID, Manu channel and cathode)
 206 - Raw charge (ADC value)
 207 - Calibrated charge
 208
 209
 210 \section rec_s6 Conversion between MUON/ESD objects
 211
 212 Every conversion between MUON objects (AliMUOVDigit/AliMUONVCluster/AliMUONTrack) and ESD objects
 213 (AliESDMuonPad/AliESDMuonCluster/AliESDMuonTrack) is done by the class AliMUONESDInterface. There are 2 ways of using this class:
 214
 215 1) Using the static methods to convert the objects one by one (and possibly put them into the provided store):
 216 - Get track parameters at vertex, at DCA, ...:
 217 \verbatim
 218   ...
 219   AliESDMuonTrack* esdTrack = esd->GetMuonTrack(iTrack);
 220   AliMUONTrackParam param;
 221   AliMUONESDInterface::GetParamAtVertex(*esdTrack, param);
 222 \endverbatim
 223
 224 - Convert an AliMUONVDigit to an AliESDMuonPad:
 225 \verbatim
 226   ...
 227   AliMUONVDigit *digit = ...;
 228   AliESDMuonPad esdPad;
 229   AliMUONESDInterface::MUONToESD(*digit, esdPad);
 230 \endverbatim
 231
 232 - Convert an AliMUONLocalTrigger to a ghost AliESDMuonTrack (containing only trigger informations):
 233 \verbatim
 234   ...
 235   AliMUONLocalTrigger* locTrg = ...;
 236   AliESDMuonTrack esdTrack;
 237   AliMUONESDInterface::MUONToESD(locTrg, esdTrack, trackId);
 238 \endverbatim
 239
 240 - Convert an AliESDMuonTrack to an AliMUONTrack:
 241 \verbatim
 242   ...
 243   AliESDMuonTrack* esdTrack = esd->GetMuonTrack(iTrack);
 244   AliMUONTrack track;
 245   AliMUONESDInterface::ESDToMUON(*esdTrack, track);
 246 \endverbatim
 247
 248 - Add an AliESDMuonTrack (converted into AliMUONTrack object) into an AliMUONVTrackStore:
 249 \verbatim
 250   ...
 251   AliESDMuonTrack* esdTrack = esd->GetMuonTrack(iTrack);
 252   AliMUONVTrackStore *trackStore = AliMUONESDInteface::NewTrackStore();
 253   AliMUONTrack* trackInStore = AliMUONESDInterface::Add(*esdTrack, *trackStore);
 254 \endverbatim
 255
 256 2) Loading an entire ESDEvent and using the finders and/or the iterators to access the corresponding MUON objects:
 257 - First load the ESD event:
 258 \verbatim
 259   AliMUONESDInterface esdInterface;
 260   esdInterface.LoadEvent(*esd);
 261 \endverbatim
 262
 263 - Get the track store:
 264 \verbatim
 265   AliMUONVTrackStore* trackStore = esdInterface.GetTracks();
 266 \endverbatim
 267
 268 - Access the number of digits in a particular cluster:
 269 \verbatim
 270   Int_t nDigits = esdInterface.GetNDigitsInCluster(clusterId);
 271 \endverbatim
 272
 273 - Find a particular digit using its ID:
 274 \verbatim
 275   AliMUONVDigit *digit = esdInterface.FindDigit(digitId);
 276 \endverbatim
 277
 278 - Find a particular cluster in a given track using their IDs:
 279 \verbatim
 280   AliMUONVCluster* cluster = esdInterface.FindCluster(trackId, clusterId);
 281 \endverbatim
 282
 283 - Iterate over all clusters of a particular track using an iterator:
 284 \verbatim
 285   TIterator* nextCluster = esdInterface.CreateClusterIterator(trackId);
 286   while ((cluster = static_cast<AliMUONVCluster*>(nextCluster()))) {...}
 287 \endverbatim
 288
 289 Note: You can change (via static method) the type of the store this class is using:
 290 \verbatim
 291   AliMUONESDInterface::UseTrackStore("name");
 292   AliMUONESDInterface::UseClusterStore("name");
 293   AliMUONESDInterface::UseDigitStore("name");
 294   AliMUONESDInterface::UseTriggerStore("name");
 295 \endverbatim
 296
 297
 298 \section rec_s7 ESD cluster/track refitting
 299
 300 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
 301 to be refitted from an instance of AliMUONESDInterface (see section @ref rec_s6), then uses the reconstruction framework to refit the
 302 objects. The reconstruction parameters are still set via the class AliMUONRecoParam (see section @ref rec_s5). The initial data are not changed.
 303 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
 304 calibration parameters without re-running the entire reconstruction.
 305
 306 To use this class we first have to connect it to the ESD interface containing MUON objects:
 307 \verbatim
 308   AliMUONRefitter refitter;
 309   refitter.Connect(&esdInterface);
 310 \endverbatim
 311
 312 We can then:
 313 - Re-clusterize the ESD clusters using the attached ESD pads (several new clusters can be reconstructed per ESD cluster):
 314 \verbatim
 315   AliMUONVClusterStore* clusterStore = refitter.ReClusterize(iTrack, iCluster);
 316   AliMUONVClusterStore* clusterStore = refitter.ReClusterize(clusterId);
 317 \endverbatim
 318
 319 - Re-fit the ESD tracks using the attached ESD clusters:
 320 \verbatim
 321   AliMUONTrack* track = refitter.RetrackFromClusters(iTrack);
 322   AliMUONVTrackStore* trackStore = refitter.ReconstructFromClusters();
 323 \endverbatim
 324
 325 - Reconstruct the ESD tracks from ESD pads (i.e. re-clusterize the attached clusters). Consider all the combination of clusters and return only
 326   the best one:
 327 \verbatim
 328   AliMUONTrack* track = refitter.RetrackFromDigits(iTrack);
 329   AliMUONVTrackStore* trackStore = refitter.ReconstructFromDigits();
 330 \endverbatim
 331
 332 The macro MUONRefit.C is an example of using this class. The results are stored in a new AliESDs.root file.
 333
 334
 335 This chapter is defined in the READMErec.txt file.
 336
 337 */