MUON/README.txt

   1 // $Id$
   2
   3 /*!
   4
   5 \page README_main README main
   6
   7 Please add  to this README file all information concerning
   8 general items about the MUON code or the libraries
   9 \ref base, \ref sim and \ref rec.
  10
  11 Other README pages of the muon code are
  12 - \ref README_raw
  13 - \ref README_mapping
  14 - \ref README_calib
  15 - \ref README_geometry
  16 - \ref README_trigger
  17 - \ref README_shuttle
  18 - \ref README_evaluation
  19 - \ref README_fast
  20
  21 \section s1 How to check that your aliroot is working well
  22
  23 There is a script file AlirootRun_MUONtest.sh which
  24 allows for simulating, reconstructing and making the
  25 invariant analysis of the generated Upsilon (1S).
  26 The used configuration file is Config.C in MUON
  27 directory.
  28
  29 You have to type :
  30 <pre>
  31 $ALICE_ROOT/MUON/AlirootRun_MUONtest.sh [option]
  32 </pre>
  33
  34 The complete list of the option is printed when you call
  35 the script with whatever non valid option, .eg. h:
  36
  37 <pre>
  38 ./AlirootRun_MUONtest.sh h
  39 ERROR : extra option not recognized
  40 Usage: AlirootRun_MUONtest.sh options (-SRXsrxn:p:d:c:)
  41        -S (-s) perform (or not) simulation (default is do it, i.e -S)
  42        -R (-r) perform (or not) reconstruction (default is do it, i.e. -R)
  43        -X event (-x) perform (or not) checks and dumps (default is do it for event 5, i.e. -X 5)
  44        -n nevents (int) number of events to simulate (default 100)
  45        -p recoptions (quotified string) reconstruction options to use (default "SAVEDIGITS")
  46        -d full path to output directory (default /work/projects/alice/dev/AliRoot/MUON/test_out.100)
  47        -c full path to configuration file for simulation (default /work/projects/alice/dev/AliRoot/MUON/Config.C)
  48 </pre>
  49
  50 The results of this test are saved in test_out.nevent directory.
  51 Please note that the CDB (Condition DataBase) is now always *required*
  52 to perform either simulation or reconstruction. For the moment, a version
  53 of that CDB is stored in CVS, so you should have one already in MUON/Calib
  54 subdirectories.
  55
  56
  57 \section s2 How to check that your aliroot is working VERY well
  58
  59 There is a script file AlirootRun_MUONlongtest.sh which
  60 allows for simulating, reconstructing and making the
  61 -+invariant analysis of the generated Upsilon (1S).
  62 This script generates a large number of Upsilon (20k)
  63 in order to access differential quantities.
  64 The used configuration file is Config.C in MUON
  65 directory.
  66
  67 One should really run this script to check if the MUON
  68 code can process a large number of events WITHOUT errors,
  69 in particular before making important commits !!
  70
  71 You have to type :
  72 <pre>
  73 $ALICE_ROOT/MUON/AlirootRun_MUONtestlong.sh
  74 </pre>
  75 The results of this test are saved in testlong_out/ directory
  76 and will be kept in CVS
  77
  78 (NOTE: the macros performing the calculations/plots MUONefficiency.C
  79 and MUONplotEfficiency.C are also able to handle J/Psi if
  80 Config.C is modified accordingly )
  81
  82 \section s3  How to run a MUON generation
  83
  84 You only need to run the simulation part of the test script
  85 AlirootRun_MUONtest.sh
  86
  87 \section s4 How to dump the content of Root data files
  88
  89 To check the content of Root data files, the AliMUON*DataInterface classes
  90 provides the functions to produce an ASCII output on the screen
  91 which can be redirected on the file:
  92
  93 for MC information, use AliMUONMCDataInterface :
  94
  95 <pre>
  96 > aliroot (or root with just the loading of MUON libs, see loadlibs.C)
  97 root [0] AliMUONMCDataInterface mcdi("galice.root");
  98 root [1] mcdi.DumpKine(5);       > dump.kine
  99 root [2] mcdi.DumpHits(5);       > dump.hits
 100 root [3] mcdi.DumpTrackRefs(5);  > dump.trackrefs
 101 </pre>
 102
 103 for all other information, use AliMUONDataInterface :
 104
 105 <pre>
 106 > aliroot
 107 root [0] AliMUONDataInterface di("galice.root");
 108 root [1] di.DumpDigits(5);     > dump.digits
 109 root [2] di.DumpSDigits(5);    > dump.sdigits
 110 root [3] di.DumpRecPoints(5);  > dump.recpoints
 111 root [4] di.DumpTrigger(5); > dump.rectrigger
 112 </pre>
 113
 114 Remind that during simulation and reconstruction two
 115 differents galice.root are generated: one for the generation
 116 (simulation) and other during the reconstruction.
 117
 118 If you open the wrong galice.root file you could get:
 119 root [0] AliMUONMCDataInterface mcdi("galice.root");
 120 root [1] mcdi.DumpKine(5);
 121 W-AliRunLoader::GetEvent: Stack not found in header
 122 E-TFile::TFile: file ./Kinematics.root does not exist
 123
 124 \section s5 Tracking parameters, cuts, energy loss and physics processes
 125
 126 Tracking parameters in MUON are automatically defined by GEANT
 127 MUON takes the default values of CUTs  and physics processes
 128 defined by the Config files, except for the gas mixture medium
 129 of the tracking chambers. The CUT's and physics processes of
 130 the gas mixture medium  is then defined in the galice.cuts file
 131 in the data directory. In particular ILOSS parameter MUST be
 132 equal unity (1) in order simulate a realistic energy loss
 133 distribution (mean value and fluctuations) in the active gas.
 134
 135 \section s6  Tracking of particle in the magnetic field
 136
 137 GEANT has two ways for tracking charged particles in the
 138 magnetic field: HELIX et RKUTA.
 139 HELIX is faster and works well if the gradient of magnetic
 140 field is small.
 141 For MUON, HELIX is a not a good approximation and we must
 142 use RKUTA to get the optimal mass resolution of the
 143 spectrometer. The choice of HELIX or RKUTA is done in the
 144 config file when the magnetic field is defined:
 145 <pre>
 146   AliMagFMaps* field = new AliMagFMaps("Maps","Maps", TRACKING, FACTOR, MAXB, AliMagFMaps::k5kG);
 147   gAlice->SetField(field);
 148 </pre>
 149 TRACKING must be 1 for RKUTA and 2 for HELIX (the default value for aliroot is 2 (HELIX))
 150 FACTOR allows you to set the magnetic field to 0, just putting FACTOR=0. Default value is 1.
 151 MAXB is the maximum magnetic field which is 10.T
 152
 153 \section s7 How to tune muon track reconstruction
 154
 155 Several options and adjustable parameters are available for both Kalman and Original
 156 tracking algorithms (hard coded for the moment in AliMUONVTrackReconstructor.cxx):
 157 - *fgkSigmaToCutForTracking* : quality cut used to select new clusters to be
 158   attached to the track candidate and to select good tracks.
 159 - *fgkMakeTrackCandidatesFast* : if this flag is set to 'true', the track candidates
 160   are made assuming linear propagation between stations 4 and 5.
 161 - *fgkTrackAllTracks* : according to the value of this flag, in case that several
 162   new clusters pass the quality cut, either we consider all the possibilities
 163   (duplicating tracks) or we attach only the best cluster.
 164 - *fgkRecoverTracks* : if this flag is set to 'true', we try to recover the tracks
 165   lost during the tracking by removing the worst of the 2 clusters attached in the
 166   previous station.
 167 - *fgkImproveTracks* : if this flag is set to 'true', we try to improve the quality
 168   of the tracks at the end of the tracking by removing clusters that do not pass
 169   new quality cut (within the limit that we must keep at least one cluster per
 170   the station).
 171 - *fgkSigmaToCutForImprovement* : quality cut used when we try to improve the
 172   quality of the tracks.
 173
 174 \section s8 MUON cocktail for physics ..............
 175
 176 There is a MUON cocktail generator of the muon sources in the
 177 EVGEN directory. This class derives from AliGenCocktail.
 178 In the init of this class I have filled the cocktail with
 179 the muon sources: J/Psi, Upsilon, Open Charm, Open Beauty,
 180 Pion, Kaons. The code needs only the production cross section
 181 at 4pi (for the moment this values are in the code since I
 182 prefere them do not be modified), and the code calculates the
 183 rate of particles in the acceptance, making the scaling based
 184 on the number of collisions for the hard probes and on the
 185 number of participants for soft sources: Pions and Kaons.
 186
 187 In the Genereate of this class all entries in the cocktail
 188 are called and we define a "primordial trigger" with requires
 189 a minimum number of muons above a Pt cut in the required acceptance.
 190 In order to normalized to the real number of simulated events,
 191 there are 2 data members in the class fNsuceeded adn fNGenerate
 192 which tell us what is the biais source.
 193
 194 Enclose an example to use this generator:
 195 <pre>
 196 AliGenMUONCocktail * gener = new AliGenMUONCocktail();
 197 gener->SetPtRange(1.,100.);       // Transverse momentum range
 198 gener->SetPhiRange(0.,360.);    // Azimuthal angle range
 199 gener->SetYRange(-4.0,-2.4);
 200 gener->SetMuonPtCut(1.);
 201 gener->SetMuonThetaCut(171.,178.);
 202 gener->SetMuonMultiplicity(2);
 203 gener->SetImpactParameterRange(0.,5.); // 10% most centra PbPb collisions
 204 gener->SetVertexSmear(kPerTrack);
 205 gener->SetOrigin(0,0,0);        // Vertex position
 206 gener->SetSigma(0,0,0.0);       // Sigma in (X,Y,Z) (cm) on IP position
 207 gener->Init();
 208 </pre>
 209
 210
 211 \section s9 How to simulate events with misaligned geometry in local CDB
 212
 213 If you want to use a misaligned geometry to simulate some
 214 events you can use a local CDB. For this need to follow
 215 the next steps:
 216
 217 - Generate misaligned data in local CDB.
 218 You can use MUONGenerateGeometryData.C as described above in
 219 the corresponding section. Let's assume you used the default
 220 residual misalignment settings, then you have a local CDB in
 221 your working directory called ResMisAlignCDB containing
 222 misalignement data (ResMisAlignCDB/MUON/Align).
 223
 224 - Tell AliSimulation you want to use your local CDB for
 225 MUON/Align/Data
 226 To do this you need to instantiate the AliCDBManager, set the
 227 default storage and set the specific storage for MUON/Align/Data,
 228 before instantiating AliSimulation (see for example the commented
 229 lines AlirootRun_MUONtest.sh).
 230
 231 <pre>
 232 aliroot -b  >& testSim.out << EOF
 233 AliCDBManager* man = AliCDBManager::Instance();
 234 man->SetDefaultStorage("local://$ALICE_ROOT");
 235 man->SetSpecificStorage("MUON/align/Data","local://ResMisAlignCDB");
 236 AliSimulation MuonSim("$ALICE_ROOT/MUON/Config.C");
 237 MuonSim.SetWriteRawData("MUON");
 238 MuonSim.Run(10);
 239 .q
 240 EOF
 241 </pre>
 242
 243 \section s10 How to Merge events
 244
 245 You can merge 2 types of simulated events. For example,
 246 you can simulate Hijing events, and then simulate muons
 247 merging both.
 248
 249 Merging is done at the sdigits level, so Kinematics files
 250 of the merged events will just correspond to the
 251 Config.C simulated file).
 252
 253 You must, first, do the Hijing simulation and store it
 254 in directory $HIJING_SIM. Note that for merging you
 255 won't need Kinematics files of the Hijing simulation...
 256
 257 Hijing simulation
 258
 259 <pre>
 260 aliroot -b << EOF
 261 AliSimulation HijingSim("$HIJING_SIM/YourConfigForHIJING.C")
 262 HijingSim.Run(5)
 263 .q
 264 EOF
 265 </pre>
 266
 267 You cand build YourConfigFroHIJING.C File from the
 268 ConfigPPR file in AliRoot/macros module.
 269
 270 Then you can do muon simulation and reconstruction
 271 merging both simulated events. In next example, we are
 272 merging 20 times each Hijing event in order to simulate
 273 100 muons merged with 5 Hijing events.
 274
 275 <pre>
 276 aliroot -b << EOF
 277 AliSimulation MuonSim("$ALICE_ROOT/MUON/Config.C")
 278 MuonSim.MergeWith("$HIJING_SIM/galice.root",20) //parameters are the Hijing simulation file and the number of times we use each Hijing event
 279 MuonSim.Run(100) // number of muon (Config.C) events
 280 .q
 281 EOF
 282
 283
 284 aliroot -b << EOF
 285 TPluginManager * pluginmanager = gROOT->GetPluginManager()
 286 pluginmanager->AddHandler("AliReconstructor","MUON","AliMUONReconstructor","MUON","AliMUONReconstructor()")
 287 AliReconstruction  MuonRec("galice.root")
 288 MuonRec.SetRunTracking("")
 289 MuonRec.SetRunVertexFinder(kFALSE)
 290 MuonRec.SetRunLocalReconstruction("MUON")
 291 MuonRec.SetFillESD("MUON")
 292 MuonRec.Run()
 293 .q
 294 EOF
 295 </pre>
 296
 297 \section s11 ...On track numbering
 298
 299 All generated particles, including primary and secondary
 300 particles are put on the stack. The secondary particles are kept
 301 in the stack only if they gave a hit in *any* of the ALICE detectors
 302 The number of all particles placed on the stack for a given event
 303 can be obtained with
 304 Int_t nPart = AliStack::GetNtrack();
 305 Looping from 0 to nPart via AliStack::Particle(ipart)
 306 gives the particle listing as obtained from the particle generator (primaries)
 307 and Monte Carlo (secondaries).
 308
 309 The particle response in the detector, a hit, is registered
 310 in the hits tree and the hits are filled with each primary track.
 311 The total number of "tracks" (fills of the tree) can be obtained
 312 with ntracks = AliMUONMCDataInterface::NumberOfTracks(event) and is usually smaller than "nPart".
 313 Since particles can also deposit hits in other detectors than
 314 the MUON spectrometer, there will be many "tracks" (fills) in the hit-tree
 315 without a hit in MUON.
 316
 317 The correspondence between "track ID" in the hits-tree ("itr") and the
 318 particle ID for particles on the stack (i.e. generated particles) can be
 319 obtained via:
 320 <pre>
 321 for (Int_t itr = 0; itr < ntracks; itr++) {
 322     AliMUONVHitStore* hitStore = mcDataInterface.HitStore(event,itr);
 323     //track "itr" of the hits-tree
 324     Int_t nhitstot = hitStore->GetSize();
 325     AliMUONHit* mHit;
 326     TIter next(hitStore->CreateIterator());
 327     while ( ( mHit = static_cast<AliMUONHit*>(next()) ) )
 328     {
 329        Int_t id = mHit->Track(); //gives particle ID on stack
 330        TParticle* particle = mcDataInterface.Stack(event)->Particle(id);
 331     }
 332 }
 333 </pre>
 334
 335 where mcDataInterface has been obtained by
 336 AliMUONMCDataInterface mcDataInterface("galice.root");
 337
 338 During the procedure to go from hits to digits, the hits
 339 are summed up such that more than one track can contribute
 340 to a given digit. As a consequence the method
 341 Int_t AliMUONDigit::Track(Int_t trackID)
 342 takes an argument, where "trackID" runs from 0 to
 343 AliMUONDigit::Ntracks() to provide the reference to *all*
 344 tracks that contributed to it. The returned track ID is the one
 345 referred to in the hit-tree. To know which is the generated particle
 346 that deposited a given digit one has to follow the sequence of the kind:
 347 (shown here using the simple, but not fast, DataInterface interfaces) :
 348
 349 <pre>
 350 AliMUONMCDataInterface mcdi("galice.root");
 351 AliMUONDataInterface di("galice.root");
 352
 353 AliMUONVDigitStore* digitStore = di.DigitStore(event);
 354 AliMUONVDigit* mDigit = ... get some digit from the digitStore
 355
 356 for (int tr = 0; tr < mDigit->Ntracks(); tr++)
 357 {
 358    Int_t hitTrackID = mDigit->Track(tr);
 359    // get the hits corresponding to this trackID
 360    AliMUONHitStore* hitStore = mcdi.HitStore(event,hitTrackID);
 361    // loop over the hits
 362    TIter hNext(hitStore->CreateIterator());
 363    AliMUONHit* mHit;
 364    while ( ( mHit = static_cast<AliMUONHit*>(hNext()) ) )
 365    {
 366     Int_t numPart = mHit->Track(); //gives ID of particle on the stack
 367     Int_t idTrack = mHit->Particle(); //gives flavour code of the particle
 368    }
 369 }
 370 </pre>
 371
 372
 373 \section s12 How to process invariant mass spectra for J/psi or Upsilon
 374
 375 The macro MUONmassPlot_ESD.C reads back the MUON ESD informations and compute
 376 the invariant mass spectra and corresponding uncorelated background.
 377 Moreover gives the number of event in the resonance peak and the number of triggers.
 378 <pre>
 379 Usage:
 380 root [0] .L $ALICE_ROOT/MUON/MUONmassPlot_ESD.C+
 381 root [1] MUONmassPlot_ESD(ExtrapToVertex,
 382                         geoFilenam, filename
 383                         FirstEvent, LastEvent,
 384                         esdFileName,
 385                         ResType, Chi2Cut,
 386                         PtCutMin, PtCutMax,
 387                         massMin, massMax)
 388
 389 with:
 390 ExtrapToVertex (default -1)
 391       <0: no extrapolation;
 392       =0: extrapolation to (0,0,0);
 393       >0: extrapolation to ESDVertex if available, else to (0,0,0)
 394 geoFilename (default "geometry.root") geometry file name needed to extrap to vertex
 395 filename    (default "galice.root") galice root file name
 396 FirstEvent  (default 0)
 397 LastEvent   (default 10000)
 398 esdFileName (default "AliESDs.root") esd root file name
 399 ResType     (default 553):   553 for Upsilon, anything else for J/Psi
 400 Chi2Cut     (default 100):   keep only tracks with chi2 per d.o.f. < Chi2Cut
 401 PtCutMin    (default 1):     keep only tracks with transverse momentum > PtCutMin
 402 PtCutMax    (default 10000): keep only tracks with transverse momentum < PtCutMax
 403 massMin     (default 9.17 for Upsilon) keep only invariant masses with
 404 massMax     (default 9.77 for Upsilon) massMin < mass < massMax
 405 </pre>
 406
 407 \section s13  Still working ..............
 408
 409 */