Reorganized README*.txt pages to get them well ordered
authorivana <ivana@f7af4fe6-9843-0410-8265-dc069ae4e863>
Tue, 18 Dec 2007 14:01:39 +0000 (14:01 +0000)
committerivana <ivana@f7af4fe6-9843-0410-8265-dc069ae4e863>
Tue, 18 Dec 2007 14:01:39 +0000 (14:01 +0000)
also in the generated reference manual.

12 files changed:
MUON/Doxymain.h
MUON/READMEbase.txt [new file with mode: 0644]
MUON/READMEcalib.txt
MUON/READMEevaluation.txt
MUON/READMEfast.txt
MUON/READMEgeometry.txt
MUON/READMEmapping.txt
MUON/READMEraw.txt
MUON/READMErec.txt [new file with mode: 0644]
MUON/READMEshuttle.txt
MUON/READMEsim.txt [moved from MUON/README.txt with 54% similarity]
MUON/READMEtrigger.txt

index 887fcdd4337f76d5c1aefac688ed9042df94b9a5..f1df89c956f36ffb3c352766ce6d70a9bd45c8d0 100644 (file)
@@ -1,68 +1,87 @@
 /*! \mainpage MUON code documentation 
 
 This is the documentation for the MUON simulation and reconstruction code.
-It is a mix of general concepts and code implementation details...
-
-\section ssimulation Simulation
-
-The simulation encompasses the following tasks :
-
-- generation of MC particles (the kinematics of the event ends up in the TreeK
- of Kinematics#.root)                              
-  
-- tracking particles through the detector using 
-the Virtual Monte Carlo, producing AliMUONHit objects, that end up in 
- the TreeH of MUON.Hits#.root file(s). This part is steered by AliMUON and its child
-AliMUONv1 classes.
-
-- converting MC hits into AliMUONVDigit, called SDigits, that end up in the TreeS
- of the MUON.SDigits#.root file(s). A S(ummable)Digit is a pad with its associated
-charge, but no noise or electronics response function applied. Steered by AliMUONSDigitizerV2 class.
-
-- converting SDigits into Digits, by applying electronics calibrations. Actually, we de-calibrate
- the digits at this stage, by adding a pedestal and dividing by a gain, more or less. Steered
- by AliMUONDigitizerV3 class. Digits end up in TreeD of MUON.Digits#.root file(s). In addition,
- for the trigger, we create AliMUONLocalTrigger, AliMUONRegionalTrigger and AliMUONGlobalTrigger objects 
-at this stage, that ends up in TreeD as well.
-
-- convert the Digits into RAW data, in a format that should be exactly the same as real data from the
-DAQ. Performed by AliMUONRawWriter.
-
-From there on, the reconstruction can proceed, in the very same way for real or simulated data,
- as long as they are in RAW format.
-
-\section sreconstruction Reconstruction
-
-The reconstruction is a multistage process, driven by the AliMUONReconstructor class :
-
-- we read the RAW data, convert them (convert them back for simulated data) to 
-AliMUONDigit. Performed by AliMUONDigitMaker. 
-- we calibrate the digits, by subtracting pedestals and multiplying by gains. Performed
- by AliMUONDigitCalibrator. Calibrated digits might be saved (back) to TreeD.
-- we make clusters by associating digits, producing AliMUONRawCluster objects that end up
-  in TreeR of MUON.RecPoints#.root file(s). Steered by AliMUONClusterReconstructor. @ref AliMUONVClusterFinder "More..."
-
-Part of the reconstruction, but not really steered by AliMUONReconstructor, is the
- last stage, the tracking, i.e. associating clusters to form tracks. Steered by AliMUONTracker.
- Producing AliMUONTrack objects that end up in TreeT of MUON.Tracks#.root and AliESDMuonTrack objects
-that end up in the ESD (Event Summary Data), AliESDs.root file. @ref AliMUONVTrackReconstructor "More..."
-
-\section sdataaccess Data access
-
-All the simulation and reconstruction use containers (called stores in MUON jargon) to hold
- the data we're dealing with : hits, (s)digits, trigger, clusters, tracks and trigger tracks.
- All those stores share some commonalities, in particular with respect to how they are read/written from/to
- TTree. @ref AliMUONVStore "More..."
-
-See more in:
-- \ref README_main 
+It is a mix of general concepts and code implementation details.
+It is constantly updated by all dimuon code developers.
+
+The documentation is organized in the thematic pages, defined in the 
+README*.txt files, which follow the code organization in the libraries.
+Currently there are the documentation pages on
+- \ref README_sim
+- \ref README_rec
+- \ref README_base
+- \ref README_evaluation 
+- \ref README_fast
 - \ref README_raw 
 - \ref README_mapping 
 - \ref README_calib 
 - \ref README_geometry 
 - \ref README_trigger 
 - \ref README_shuttle 
-- \ref README_evaluation 
-- \ref README_fast
+
+On this page you will find the first how to run the 
+simulation, reconstructin and evaluation chain. More details
+and various macros can be found on the other pages.
+
+\section s1 How to check that your aliroot is working well
+
+There is a script file AlirootRun_MUONtest.sh which 
+allows for simulating, reconstructing and making the
+invariant analysis of the generated Upsilon (1S).
+The used configuration file is Config.C in MUON 
+directory.
+
+You have to type :
+<pre>
+$ALICE_ROOT/MUON/AlirootRun_MUONtest.sh [option]
+</pre>
+
+The complete list of the option is printed when you call
+the script with whatever non valid option, .eg. h:
+
+<pre>
+./AlirootRun_MUONtest.sh h
+ERROR : extra option not recognized
+Usage: AlirootRun_MUONtest.sh options (-SRXsrxn:p:d:c:)
+       -S (-s) perform (or not) simulation (default is do it, i.e -S)
+       -R (-r) perform (or not) reconstruction (default is do it, i.e. -R)
+       -X event (-x) perform (or not) checks and dumps (default is do it for event 5, i.e. -X 5)
+       -n nevents (int) number of events to simulate (default 100)
+       -p recoptions (quotified string) reconstruction options to use (default "SAVEDIGITS")
+       -d full path to output directory (default /work/projects/alice/dev/AliRoot/MUON/test_out.100)
+       -c full path to configuration file for simulation (default /work/projects/alice/dev/AliRoot/MUON/Config.C)
+</pre>
+
+The results of this test are saved in test_out.nevent directory.
+Please note that the CDB (Condition DataBase) is now always *required* 
+to perform either simulation or reconstruction. For the moment, a version
+of that CDB is stored in CVS, so you should have one already in MUON/Calib
+subdirectories.
+
+
+\section s2 How to check that your aliroot is working VERY well
+
+There is a script file AlirootRun_MUONlongtest.sh which
+allows for simulating, reconstructing and making the
+-+invariant analysis of the generated Upsilon (1S).
+This script generates a large number of Upsilon (20k) 
+in order to access differential quantities. 
+The used configuration file is Config.C in MUON
+directory.
+
+One should really run this script to check if the MUON 
+code can process a large number of events WITHOUT errors,
+in particular before making important commits !!
+
+You have to type :
+<pre>
+$ALICE_ROOT/MUON/AlirootRun_MUONtestlong.sh
+</pre>
+The results of this test are saved in testlong_out/ directory
+and will be kept in CVS
+
+(NOTE: the macros performing the calculations/plots MUONefficiency.C 
+and MUONplotefficiency.C are also able to handle J/Psi if 
+Config.C is modified accordingly )
 
 */
diff --git a/MUON/READMEbase.txt b/MUON/READMEbase.txt
new file mode 100644 (file)
index 0000000..c3206c6
--- /dev/null
@@ -0,0 +1,67 @@
+// $Id$
+
+/*! \page README_base Data definition and access
+
+Both the simulation and reconstruction use containers (called stores in the MUON jargon) 
+to hold the data we're dealing with: hits, (s)digits, trigger, clusters, tracks and 
+trigger tracks. All those stores share some commonalities, in particular with respect
+to how they are read/written from/to TTree. @ref AliMUONVStore "More..."
+
+
+\section base_s1 How to dump the content of Root data files 
+
+To check the content of Root data files, the AliMUON*DataInterface classes
+provides the functions to produce an ASCII output on the screen
+which can be redirected on the file:
+
+for MC information, use AliMUONMCDataInterface :
+
+<pre>
+> aliroot (or root with just the loading of MUON libs, see loadlibs.C)
+root [0] AliMUONMCDataInterface mcdi("galice.root");
+root [1] mcdi.DumpKine(5);       > dump.kine
+root [2] mcdi.DumpHits(5);       > dump.hits
+root [3] mcdi.DumpTrackRefs(5);  > dump.trackrefs
+</pre>
+
+for all other information, use AliMUONDataInterface :
+
+<pre>
+> aliroot
+root [0] AliMUONDataInterface di("galice.root");
+root [1] di.DumpDigits(5);     > dump.digits
+root [2] di.DumpSDigits(5);    > dump.sdigits
+root [3] di.DumpRecPoints(5);  > dump.recpoints
+root [4] di.DumpTrigger(5); > dump.rectrigger
+</pre>
+
+Remind that during simulation and reconstruction two 
+differents galice.root are generated: one for the generation 
+(simulation) and other during the reconstruction.
+
+If you open the wrong galice.root file you could get:
+root [0] AliMUONMCDataInterface mcdi("galice.root");
+root [1] mcdi.DumpKine(5);
+W-AliRunLoader::GetEvent: Stack not found in header
+E-TFile::TFile: file ./Kinematics.root does not exist
+
+This chapter is defined in the READMEbase.txt file.
+
+\section basee_s2 Macro MUONCheckDI.C
+
+MUONCheckDI.C performs a consistency check on the methods of the 
+AliMUONMCDataInterface and AliMUONDataInterface classes. There are several 
+helper methods in these classes which make it easier to fetch data, which 
+means there are at least two ways of fetching the data within the same class 
+interface. The macro checks to see that the results given by these different 
+methods are identical, as they should be.
+
+The macro also inherently exercises the AliMUONMCDataInterface and 
+AliMUONDataInterface classes and should be run after any modifications to 
+these classes to see if things still work. Putting it another way: 
+MUONCheckDI.C is a testing facility for developers of these two classes.
+
+This chapter is defined in the READMEbase.txt file (although it describes
+also the code in the evaluation library.)
+
+*/
index f53df6748ccc76effcd1dc66aca3799a041afc7c..f72b2901fc584c30dceaea82e77d9f65766cfb75 100644 (file)
@@ -2,7 +2,7 @@
 
 /*! 
 
-\page README_calib README calib
+\page README_calib Calibration
  
 The Offline Condition DataBase is described extensively on ALICE Offline pages.
 
@@ -105,5 +105,6 @@ A special kind of object is the status map. It would deserve a full documentatio
  at the MUONStatusMap.C macro which can let you play with it. For more information,
  have a look at the AliMUONPadStatusMaker and AliMUONPadStatusMapMaker.
 
+This chapter is defined in the READMEcalib.txt file.
 */
 
index c52135cd46f673d7ca503fbb61b2bcc32a68e300..55938cba48588f5c7d9fde100309ea1e101c43ac 100644 (file)
@@ -2,10 +2,44 @@
 
 /*! 
 
-\page README_evaluation README evaluation
+\page README_evaluation Evaluation
  
 
-\section evaluation_s1 How to run MUONRecoCheck macro
+\section  evaluation_s1 How to process invariant mass spectra for J/psi or Upsilon
+
+The macro MUONmassPlot_ESD.C reads back the MUON ESD informations and compute 
+the invariant mass spectra and corresponding uncorelated background. 
+Moreover gives the number of event in the resonance peak and the number of triggers.
+<pre>
+Usage:
+root [0] .L $ALICE_ROOT/MUON/MUONmassPlot_ESD.C+
+root [1] MUONmassPlot_ESD(ExtrapToVertex, 
+                       geoFilenam, filename
+                        FirstEvent, LastEvent, 
+                       esdFileName,
+                       ResType, Chi2Cut,
+                       PtCutMin, PtCutMax,
+                       massMin, massMax)
+
+with:
+ExtrapToVertex (default -1)
+      <0: no extrapolation;
+      =0: extrapolation to (0,0,0);
+      >0: extrapolation to ESDVertex if available, else to (0,0,0)
+geoFilename (default "geometry.root") geometry file name needed to extrap to vertex
+filename    (default "galice.root") galice root file name
+FirstEvent  (default 0)
+LastEvent   (default 10000)
+esdFileName (default "AliESDs.root") esd root file name
+ResType     (default 553):   553 for Upsilon, anything else for J/Psi
+Chi2Cut     (default 100):   keep only tracks with chi2 per d.o.f. < Chi2Cut
+PtCutMin    (default 1):     keep only tracks with transverse momentum > PtCutMin
+PtCutMax    (default 10000): keep only tracks with transverse momentum < PtCutMax
+massMin     (default 9.17 for Upsilon) keep only invariant masses with 
+massMax     (default 9.77 for Upsilon) massMin < mass < massMax
+</pre>
+
+\section evaluation_s2 How to run MUONRecoCheck macro
 
 To check the muon reconstruction by comparing the reconstructed tracks
 with the reference tracks made of "AliTrackReference" for the hits in chamber (0..9)
@@ -27,7 +61,7 @@ MUONRecoCheck(nEvent,"geometry.root", "galice.root"); // nEvent = nb of events
 </pre>
 
 
-\section evaluation_s2 Macros for MC studies
+\section evaluation_s3 Macros for MC studies
 
 For MC studies the classes AliMUONTrackLight and AliMUONPairLight can be 
 used in order to fill not only the single muon / dimuon's kinematics (charge, 
@@ -74,18 +108,6 @@ ReadRecoCocktail();
 .q
 </pre>
 
-\section evaluation_s3 Macro MUONCheckDI.C
-
-MUONCheckDI.C performs a consistency check on the methods of the 
-AliMUONMCDataInterface and AliMUONDataInterface classes. There are several 
-helper methods in these classes which make it easier to fetch data, which 
-means there are at least two ways of fetching the data within the same class 
-interface. The macro checks to see that the results given by these different 
-methods are identical, as they should be.
-
-The macro also inherently exercises the AliMUONMCDataInterface and 
-AliMUONDataInterface classes and should be run after any modifications to 
-these classes to see if things still work. Putting it another way: 
-MUONCheckDI.C is a testing facility for developers of these two classes.
+This chapter is defined in the READMEevaluation.txt file.
 
 */
index 33ce195616041459b1e43e4c3bad56772d0ceac8..f95244dfa189837a6d84fd333d1dad3ec280e80d 100644 (file)
@@ -2,11 +2,9 @@
 
 /*! 
 
-\page README_fast README fast
+\page README_fast Fast simulation
 
 
-\section fast_s1 How to test the fast simulation for MUON.
-
 The macro fastMUONGen.C allows to generate events using the 
 AliGenMUONCocktailpp generator. In the current implementation, the 
 generator is set up in order to force all generated particles to decay
@@ -29,6 +27,8 @@ that are built on the basis of the surviving muons.
 
 Both macros can be run from fastSim.sh test script.
 
+This chapter is defined in the READMEfast.txt file.
+
 */
 
 
index b47093ed768a846279e55de346973b817f6b1e61..952e8acd8ed9280b31d88277f708b5148be0b377 100644 (file)
@@ -2,37 +2,35 @@
 
 /*! 
 
-\page README_geometry README geometry
+\page README_geometry Geometry
 
 
 \section geometry_s1 General Information about MUON Geometry
 
 Our geometry is described in the geometry builder classes.
-Main geometrical constants are set in the class AliMUONConstants.
-The code can then generate the geometry data files
-transform.dat and svmap.dat (see description below) via the macro  
-MUONGenerateGeometryData.C (more info below).
-
-The geometry data files have to be recreated each time the code 
-of the geometry is modified. The info (well updated) in this files 
-(svmap) is need during the simulation.
+The main geometrical constants are set in the class AliMUONConstants.
+The geometry is built from the code during running simulation
+and it is automatically exported in a geometry.root file
+via the framework. Then  aliroot takes this geometry.root file as 
+a unique geometrical info of our apparatus during the generation 
+and the reconstruction and analysis (if needed)
+
+The code can also generate the special geometry 
+data files, transform.dat and svmap.dat, via the macro  
+MUONGenerateGeometryData.C (see more in \ref geometry_s4 below).
+The svmap.dat data file have to be recreated each time the code 
+of the geometry is modified. The info (well updated) in this file 
+is needed during the simulation.
 We can also decide to use the transform.dat file as input of our 
 geometry. This allows for changing the position of our detection elements
 and/or half-planes (half-chambers in code jargon) without modifying 
 and recompiling the code. 
 
-First step in the official aliroot simulation process is to create 
-the geometry.root file from the builders to build the MUON geometry 
-within the geometrical modeler framework of root. 
-Then  aliroot takes the geometry.root file as a unique geometrical 
-info of our apparatus during the generation and the reconstruction
-and analysis (if needed)
-
 Misalignments are in the official AliRoot code applied to the geometry.root
 file.
 
 
-\section geometry_s2 How to check the Geometry with the new Geometrical modeler
+\section geometry_s2 How to check the geometry with the Root geometrical modeler
 
 \see ftp://root.cern.ch/root/doc/chapter16.pdf
 \see http://agenda.cern.ch/fullAgenda.php?ida=a05212
@@ -43,7 +41,7 @@ gGeoManager->GetMasterVolume()->Draw();
 </pre>
 
 
-\section geometry_s3  How to check the overlap with the new Geometrical modeler
+\section geometry_s3  How to check the overlaps with the Root geometrical modeler
 
 \see  ftp://root.cern.ch/root/doc/chapter16.pdf
 \see  http://agenda.cern.ch/fullAgenda.php?ida=a05212
@@ -57,12 +55,7 @@ gGeoManager->PrintOverlaps();
 
 \section geometry_s4 Macro  MUONGenerateGeometryData.C
                                                
-Macro for generating the geometry data files
-
-Geometry data files:
-- MUON/data/transform.dat file contains the transformations
-data (translation and rotation) for all alignable objects
-(modules & detection elements)
+Macro for generating the geometry data files:
 - MUON/data/svmap.dat file contains all the information to link 
 each geant volume (it can be extended to other virtual MC) with
 a detection element. The point here is that a given detection
@@ -71,6 +64,9 @@ the correspondence is then defined in an input file.
 Each time there is a change in the definition of MC geometry, these
 input files must be re-generated via the macro  
 MUONGenerateGeometryData.C
+- MUON/data/transform.dat file contains the transformations
+data (translation and rotation) for all alignable objects
+(modules & detection elements)
 
 To be run from aliroot:
 <pre>
@@ -91,12 +87,14 @@ Macros for generating the geometry mis-alignment data:
 
 To be run from aliroot:
 <pre>
-.x MakeMUONFullMisAlignment.C etc.
+.x MakeMUONFullMisAlignment.C
 </pre>
 
+etc.
+
 If the environment variable TOCDB is not set to "kTRUE",
 the misalignment data are generated in a local file:
-(MUONFullMisalignment.root, etc.)
+MUONFullMisalignment.root, etc.
 
 If the data are stored in CDB, the storage can be specified in 
 the environment variable STORAGE. The misalignment data are then
@@ -141,10 +139,10 @@ The macro MUONCheckMisAligner.C performs the misalignment on an existing muon
 arm geometry based on the standard definition of the detector elements.
 
 It uses AliMUONGeometryAligner : 
-- creates a new AliMUONGeometryTransformer and AliMUONGeometryAligner
-- reads the transformations in from the transform.dat file (make sure that
+- Creates a new AliMUONGeometryTransformer and AliMUONGeometryAligner
+- Reads the transformations in from the transform.dat file (make sure that
 this file is the _standard_ one by comparing it to the one in CVS)
-- creates a second AliMUONGeometryTransformer by misaligning the existing 
+- Creates a second AliMUONGeometryTransformer by misaligning the existing 
 one using AliMUONAligner::MisAlign
 
 User has to specify the magnitude of the alignments, in the Cartesian 
@@ -172,7 +170,7 @@ x,y,theta_xy, but in principle z and the other two angles are alignable
 as well.  
 
 
-\section geometry_s8 Geometry data files description
+\section geometry_s8 Geometry data files format
  
 \subsection geometry_s8_sub1 transform.dat
  
@@ -201,4 +199,6 @@ as well.
  </pre>
 
 
+This chapter is defined in the READMEgeometry.txt file.
+
 */
index 239ed2341c36be30414b1e0d725791721b86c5a8..b2a99d40f7538bf79dd98886e41606f3f68f84a4 100644 (file)
@@ -2,11 +2,14 @@
 
 /*! 
 
-\page README_mapping README mapping
+\page README_mapping Mapping
  
 
-See detailed description in ALICE-INT-2003-025.
-
+See the detailed description of the mapping package in ALICE-INT-2003-025.
+Since that time the mapping has been extended for slat and trigger
+chamber segmentations an later on also to hold the description of the
+top level connections of detection elements, including information
+about DDLs, bus patches and also trigger configuration.
 
 \section mapping_s1  Graphical User Interface
   
@@ -40,46 +43,19 @@ The GUI allows:
 
 \section mapping_s2 Test macros
 
+A set of tests macros have been written during the development
+of the mapping classes. To run these macros:
+
 <pre>
    cd ../mapping/macro
    root
    root [0] .x testMacroName.C    
-                      see available macros below   
 </pre>
                    
-A set of test macros be run at once by test_suite.pl scripts:
--  test_suite.pl      - run all test macros and compare results with
-                        the reference output
--  test_suite_ref.pl  - generates reference output
-                       !! this script will overwrite the refence output
-                          provided with the source;
-                          it should be used only by developers 
-
-Macros included in the test suite:
--  testReadSector.C
--  testReadMotifType.C
--  testGraphics.C        
--  testSectorFind.C
--  testPlaneFind.C
--  testPrintLimits.C         
--  testExistingPads.C    
--  testPadDimensions.C    
--  testSectorPadIterators.C
--  testMotifTypeIterators.C     
--  testNeighboursPadIterator.C  
--  testAnyPadIterators.C  
--  testPadsUp.C
--  testPlaneAreaIterator.C
-  
-Other macros (not included in the test suite):
--  testAllIndices.C
--  testUpdateGlobalIndices.C
-   
 
 \section mapping_s3  Data files format
 
-
-\subsection mapping_s3_sub1  zones.dat:
+\subsection mapping_s3_sub1  zones.dat
 
 Describes layout of zones, rows, row segments, subzones, motifs
 
@@ -110,7 +86,7 @@ Describes layout of zones, rows, row segments, subzones, motifs
 </pre>
   
 
-\subsection mapping_s3_sub2  zones_special.dat:
+\subsection mapping_s3_sub2  zones_special.dat
 
 Describes layout of special row segments (with irregular motifs)
 
@@ -171,7 +147,7 @@ the local pad indices (i,j)
 </pre>
   
 
-\subsection mapping_s3_sub4  *.pcb files
+\subsection mapping_s3_sub5  *.pcb files
 
 Lines starting with # are comments.
 
@@ -196,7 +172,7 @@ computed from the motif alone (but that serves as a cross-check that the motif
 pattern given is ok). That's not the case for short or rounded PCB though.
 
 
-\subsection mapping_s3_sub5  *.slat files
+\subsection mapping_s3_sub6  *.slat files
 
 A slat is defined by the list of its PCB, described starting 
 from the beam and going outward.
@@ -225,7 +201,7 @@ Note that the definition of the PCBs have to be in files with extension
 .pcb (X.pcb, Y.pcb, Z.pcb)
 
   
-\subsection mapping_s3_sub6  DetElemIdToBusPatch.dat
+\subsection mapping_s3_sub7  DetElemIdToBusPatch.dat
 
 Lines starting with # are comments.
 
@@ -238,7 +214,7 @@ The DDL id is needed for the rawdata generation only.
 To generate this file, the macro MUONGenerateBusPatch.C could be used.
 
 
-\subsection mapping_s3_sub7  crate.dat
+\subsection mapping_s3_sub8  crate.dat
   
 Muon trigger electronics configuration file (decoded in class 
 AliMUONTriggerCrateStore) directly copy/paste from the ALICE PRR 
@@ -251,5 +227,7 @@ crate name it belongs to, slot number, and internal switches
  
 Lengths are in centimeters.
  
+This chapter is defined in the READMEmapping.txt file.
+
 */
   
index 0487ece63499fce466e34e1aaab249bcda486cfe..89dee038f7fd5651e4026f8cee921cbc883b085d 100644 (file)
@@ -2,7 +2,7 @@
 
 /*! 
 
-\page README_raw README raw
+\page README_raw Raw data
  
 \section raw_s1 How to read & decode raw data 
 
@@ -54,5 +54,7 @@ where the raw0...n subdirectories are located:
 MUONRawStreamTracker(..)(maxEvent, firstDDL, lastDDL, "$YOUR_WORKING_DIRECTORY/"); //Do not forget the slash at the end!
 </pre>
 
+This chapter is defined in the READMEraw.txt file.
+
 */
 
diff --git a/MUON/READMErec.txt b/MUON/READMErec.txt
new file mode 100644 (file)
index 0000000..f642e25
--- /dev/null
@@ -0,0 +1,45 @@
+// $Id$
+
+/*! 
+
+\page README_rec Reconstruction
+The reconstruction is a multistage process, driven by the AliMUONReconstructor class :
+
+- We read the RAW data, convert them (convert them back for simulated data) to 
+AliMUONDigit. Performed by AliMUONDigitMaker. 
+- We calibrate the digits, by subtracting pedestals and multiplying by gains. Performed
+ by AliMUONDigitCalibrator. Calibrated digits might be saved (back) to TreeD.
+- We make clusters by associating digits, producing AliMUONRawCluster objects that end up
+  in TreeR of MUON.RecPoints#.root file(s). Steered by AliMUONClusterReconstructor. @ref AliMUONVClusterFinder "More..."
+
+Part of the reconstruction, but not really steered by AliMUONReconstructor, is the
+ last stage, the tracking, i.e. associating clusters to form tracks. Steered by AliMUONTracker.
+ Producing AliMUONTrack objects that end up in TreeT of MUON.Tracks#.root and AliESDMuonTrack objects
+that end up in the ESD (Event Summary Data), AliESDs.root file. @ref AliMUONVTrackReconstructor "More..."
+
+
+\section rec_s1 How to tune muon track reconstruction
+
+Several options and adjustable parameters are available for both Kalman and Original
+tracking algorithms (hard coded for the moment in AliMUONVTrackReconstructor.cxx):
+- *fgkSigmaToCutForTracking* : quality cut used to select new clusters to be
+  attached to the track candidate and to select good tracks.
+- *fgkMakeTrackCandidatesFast* : if this flag is set to 'true', the track candidates
+  are made assuming linear propagation between stations 4 and 5.
+- *fgkTrackAllTracks* : according to the value of this flag, in case that several
+  new clusters pass the quality cut, either we consider all the possibilities
+  (duplicating tracks) or we attach only the best cluster.
+- *fgkRecoverTracks* : if this flag is set to 'true', we try to recover the tracks
+  lost during the tracking by removing the worst of the 2 clusters attached in the
+  previous station.
+- *fgkImproveTracks* : if this flag is set to 'true', we try to improve the quality
+  of the tracks at the end of the tracking by removing clusters that do not pass
+  new quality cut (within the limit that we must keep at least one cluster per
+  the station).
+- *fgkSigmaToCutForImprovement* : quality cut used when we try to improve the
+  quality of the tracks.
+
+This chapter is defined in the READMEraw.txt file.
+
+*/
index 7c11ffe8d4b75cf854290e31f18f7456ea5d6c40..e519dd09e70acbb6d8f9e87ed6bf6d0f599494af 100644 (file)
@@ -2,7 +2,7 @@
 
 /*! 
 
-\page README_shuttle README shuttle 
+\page README_shuttle Shuttle 
 
 How to test the Shuttle preprocessor(s) for MUON.
 
@@ -200,5 +200,7 @@ The matrices of TGeoHMatrix type, with TObject::fUniqueID equal to the geometry
 module Id, are put in a TClonesArray and saved in the Root file with a 
 key "GMSarray".
 
+This chapter is defined in the READMEshuttle.txt file.
+
 */
  
similarity index 54%
rename from MUON/README.txt
rename to MUON/READMEsim.txt
index 9cd8082e616a5b19141d0b2fbe1ebe7a052ff2e8..38cb6c0990547240adc71c2aa8263bcc5817df1f 100644 (file)
 // $Id$
 
-/*! 
+/*! \page README_sim Simulation 
 
-\page README_main README main
-Please add  to this README file all information concerning 
-general items about the MUON code or the libraries 
-\ref base, \ref sim and \ref rec.
-
-Other README pages of the muon code are
-- \ref README_raw 
-- \ref README_mapping 
-- \ref README_calib 
-- \ref README_geometry 
-- \ref README_trigger 
-- \ref README_shuttle 
-- \ref README_evaluation 
-- \ref README_fast
-
-\section s1 How to check that your aliroot is working well
-
-There is a script file AlirootRun_MUONtest.sh which 
-allows for simulating, reconstructing and making the
-invariant analysis of the generated Upsilon (1S).
-The used configuration file is Config.C in MUON 
-directory.
-
-You have to type :
-<pre>
-$ALICE_ROOT/MUON/AlirootRun_MUONtest.sh [option]
-</pre>
-
-The complete list of the option is printed when you call
-the script with whatever non valid option, .eg. h:
-
-<pre>
-./AlirootRun_MUONtest.sh h
-ERROR : extra option not recognized
-Usage: AlirootRun_MUONtest.sh options (-SRXsrxn:p:d:c:)
-       -S (-s) perform (or not) simulation (default is do it, i.e -S)
-       -R (-r) perform (or not) reconstruction (default is do it, i.e. -R)
-       -X event (-x) perform (or not) checks and dumps (default is do it for event 5, i.e. -X 5)
-       -n nevents (int) number of events to simulate (default 100)
-       -p recoptions (quotified string) reconstruction options to use (default "SAVEDIGITS")
-       -d full path to output directory (default /work/projects/alice/dev/AliRoot/MUON/test_out.100)
-       -c full path to configuration file for simulation (default /work/projects/alice/dev/AliRoot/MUON/Config.C)
-</pre>
+The simulation encompasses the following tasks :
 
-The results of this test are saved in test_out.nevent directory.
-Please note that the CDB (Condition DataBase) is now always *required* 
-to perform either simulation or reconstruction. For the moment, a version
-of that CDB is stored in CVS, so you should have one already in MUON/Calib
-subdirectories.
+- Generation of MC particles (the kinematics of the event ends up in the TreeK
+ of Kinematics#.root)                              
+  
+- Tracking particles through the detector using 
+the Virtual Monte Carlo, producing AliMUONHit objects, that end up in 
+ the TreeH of MUON.Hits#.root file(s). This part is steered by AliMUON and its child
+AliMUONv1 classes.
 
+- Converting MC hits into AliMUONVDigit, called SDigits, that end up in the TreeS
+ of the MUON.SDigits#.root file(s). A S(ummable)Digit is a pad with its associated
+charge, but no noise or electronics response function applied. Steered by AliMUONSDigitizerV2 class.
 
-\section s2 How to check that your aliroot is working VERY well
+- Converting SDigits into Digits, by applying electronics calibrations. Actually, we de-calibrate
+ the digits at this stage, by adding a pedestal and dividing by a gain, more or less. Steered
+ by AliMUONDigitizerV3 class. Digits end up in TreeD of MUON.Digits#.root file(s). In addition,
+ for the trigger, we create AliMUONLocalTrigger, AliMUONRegionalTrigger and AliMUONGlobalTrigger objects 
+at this stage, that ends up in TreeD as well.
 
-There is a script file AlirootRun_MUONlongtest.sh which
-allows for simulating, reconstructing and making the
--+invariant analysis of the generated Upsilon (1S).
-This script generates a large number of Upsilon (20k) 
-in order to access differential quantities. 
-The used configuration file is Config.C in MUON
-directory.
+- Convert the Digits into RAW data, in a format that should be exactly the same as real data from the
+DAQ. Performed by AliMUONRawWriter.
 
-One should really run this script to check if the MUON 
-code can process a large number of events WITHOUT errors,
-in particular before making important commits !!
+From there on, the reconstruction can proceed, in the very same way for real or simulated data,
+ as long as they are in RAW format.
 
-You have to type :
-<pre>
-$ALICE_ROOT/MUON/AlirootRun_MUONtestlong.sh
-</pre>
-The results of this test are saved in testlong_out/ directory
-and will be kept in CVS
-
-(NOTE: the macros performing the calculations/plots MUONefficiency.C 
-and MUONplotefficiency.C are also able to handle J/Psi if 
-Config.C is modified accordingly )
-
-\section s3  How to run a MUON generation
+\section sim_s1  How to run a MUON generation
 
 You only need to run the simulation part of the test script
 AlirootRun_MUONtest.sh
 
-\section s4 How to dump the content of Root data files 
-
-To check the content of Root data files, the AliMUON*DataInterface classes
-provides the functions to produce an ASCII output on the screen
-which can be redirected on the file:
-
-for MC information, use AliMUONMCDataInterface :
-
-<pre>
-> aliroot (or root with just the loading of MUON libs, see loadlibs.C)
-root [0] AliMUONMCDataInterface mcdi("galice.root");
-root [1] mcdi.DumpKine(5);       > dump.kine
-root [2] mcdi.DumpHits(5);       > dump.hits
-root [3] mcdi.DumpTrackRefs(5);  > dump.trackrefs
-</pre>
-
-for all other information, use AliMUONDataInterface :
-
-<pre>
-> aliroot
-root [0] AliMUONDataInterface di("galice.root");
-root [1] di.DumpDigits(5);     > dump.digits
-root [2] di.DumpSDigits(5);    > dump.sdigits
-root [3] di.DumpRecPoints(5);  > dump.recpoints
-root [4] di.DumpTrigger(5); > dump.rectrigger
-</pre>
-
-Remind that during simulation and reconstruction two 
-differents galice.root are generated: one for the generation 
-(simulation) and other during the reconstruction.
 
-If you open the wrong galice.root file you could get:
-root [0] AliMUONMCDataInterface mcdi("galice.root");
-root [1] mcdi.DumpKine(5);
-W-AliRunLoader::GetEvent: Stack not found in header
-E-TFile::TFile: file ./Kinematics.root does not exist
-
-\section s5 Tracking parameters, cuts, energy loss and physics processes
+\section sim_s2 Tracking parameters, cuts, energy loss and physics processes
 
 Tracking parameters in MUON are automatically defined by GEANT
 MUON takes the default values of CUTs  and physics processes
@@ -132,7 +45,7 @@ in the data directory. In particular ILOSS parameter MUST be
 equal unity (1) in order simulate a realistic energy loss
 distribution (mean value and fluctuations) in the active gas.
 
-\section s6  Tracking of particle in the magnetic field
+\section sim_s3  Tracking of particle in the magnetic field
 
 GEANT has two ways for tracking charged particles in the 
 magnetic field: HELIX et RKUTA.
@@ -150,28 +63,7 @@ TRACKING must be 1 for RKUTA and 2 for HELIX (the default value for aliroot is 2
 FACTOR allows you to set the magnetic field to 0, just putting FACTOR=0. Default value is 1.
 MAXB is the maximum magnetic field which is 10.T
 
-\section s7 How to tune muon track reconstruction
-
-Several options and adjustable parameters are available for both Kalman and Original
-tracking algorithms (hard coded for the moment in AliMUONVTrackReconstructor.cxx):
-- *fgkSigmaToCutForTracking* : quality cut used to select new clusters to be
-  attached to the track candidate and to select good tracks.
-- *fgkMakeTrackCandidatesFast* : if this flag is set to 'true', the track candidates
-  are made assuming linear propagation between stations 4 and 5.
-- *fgkTrackAllTracks* : according to the value of this flag, in case that several
-  new clusters pass the quality cut, either we consider all the possibilities
-  (duplicating tracks) or we attach only the best cluster.
-- *fgkRecoverTracks* : if this flag is set to 'true', we try to recover the tracks
-  lost during the tracking by removing the worst of the 2 clusters attached in the
-  previous station.
-- *fgkImproveTracks* : if this flag is set to 'true', we try to improve the quality
-  of the tracks at the end of the tracking by removing clusters that do not pass
-  new quality cut (within the limit that we must keep at least one cluster per
-  the station).
-- *fgkSigmaToCutForImprovement* : quality cut used when we try to improve the
-  quality of the tracks.
-
-\section s8 MUON cocktail for physics ..............
+\section sim_s4 MUON cocktail generator
 
 There is a MUON cocktail generator of the muon sources in the
 EVGEN directory. This class derives from AliGenCocktail.
@@ -207,8 +99,7 @@ gener->SetSigma(0,0,0.0);       // Sigma in (X,Y,Z) (cm) on IP position
 gener->Init();
 </pre>
  
-
-\section s9 How to simulate events with misaligned geometry in local CDB
+\section sim_s5 How to simulate events with misaligned geometry in local CDB
 
 If you want to use a misaligned geometry to simulate some
 events you can use a local CDB. For this need to follow
@@ -240,7 +131,7 @@ MuonSim.Run(10);
 EOF
 </pre>
 
-\section s10 How to Merge events
+\section sim_s6 How to Merge events
 
 You can merge 2 types of simulated events. For example, 
 you can simulate Hijing events, and then simulate muons
@@ -294,7 +185,7 @@ MuonRec.Run()
 EOF
 </pre>
 
-\section s11 ...On track numbering 
+\section sim_s7 On track numbering 
 
 All generated particles, including primary and secondary
 particles are put on the stack. The secondary particles are kept
@@ -369,41 +260,6 @@ for (int tr = 0; tr < mDigit->Ntracks(); tr++)
 }
 </pre>
 
-
-\section s12 How to process invariant mass spectra for J/psi or Upsilon
-
-The macro MUONmassPlot_ESD.C reads back the MUON ESD informations and compute 
-the invariant mass spectra and corresponding uncorelated background. 
-Moreover gives the number of event in the resonance peak and the number of triggers.
-<pre>
-Usage:
-root [0] .L $ALICE_ROOT/MUON/MUONmassPlot_ESD.C+
-root [1] MUONmassPlot_ESD(ExtrapToVertex, 
-                       geoFilenam, filename
-                        FirstEvent, LastEvent, 
-                       esdFileName,
-                       ResType, Chi2Cut,
-                       PtCutMin, PtCutMax,
-                       massMin, massMax)
-
-with:
-ExtrapToVertex (default -1)
-      <0: no extrapolation;
-      =0: extrapolation to (0,0,0);
-      >0: extrapolation to ESDVertex if available, else to (0,0,0)
-geoFilename (default "geometry.root") geometry file name needed to extrap to vertex
-filename    (default "galice.root") galice root file name
-FirstEvent  (default 0)
-LastEvent   (default 10000)
-esdFileName (default "AliESDs.root") esd root file name
-ResType     (default 553):   553 for Upsilon, anything else for J/Psi
-Chi2Cut     (default 100):   keep only tracks with chi2 per d.o.f. < Chi2Cut
-PtCutMin    (default 1):     keep only tracks with transverse momentum > PtCutMin
-PtCutMax    (default 10000): keep only tracks with transverse momentum < PtCutMax
-massMin     (default 9.17 for Upsilon) keep only invariant masses with 
-massMax     (default 9.77 for Upsilon) massMin < mass < massMax
-</pre>
-
-\section s13  Still working ..............
+This chapter is defined in the READMEsim.txt file.
 
 */
index 0dcc6f0b9117f3d8de3ac5338edc0de02f7525d7..f7e5203c6c82295d0dc793e050dfe43a504f4637 100644 (file)
@@ -2,7 +2,7 @@
 
 /*! 
 
-\page README_trigger README trigger
+\page README_trigger Trigger
 
 
 \section trigger_s1  How to reprocess trigger decision from already produced digits
@@ -50,7 +50,7 @@ By menus:
 \subsection trigger_s2_sub1 File
 
 - Run     - open a file and start with a given event number
-          takes the full path <path>/galice.root
+            takes the full path your_path/galice.root
 - Control - navigate in the tree with events
 - Exit    - exit the main application
 
@@ -179,5 +179,7 @@ by adding in Config.C:
 MUON->SetTriggerEffCells(1);
 </pre>
 
+This chapter is defined in the READMEtrigger.txt file.
+
 */