MUON/README

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