[u/mrichter/AliRoot.git] / MUON / README

/**************************************************************************
 * Copyright(c) 1998-1999, ALICE Experiment at CERN, All rights reserved. *
 *                                                                        *
 * Author: The ALICE Off-line Project.                                    *
 * Contributors are mentioned in the code where appropriate.              *
 *                                                                        *
 * Permission to use, copy, modify and distribute this software and its   *
 * documentation strictly for non-commercial purposes is hereby granted   *
 * without fee, provided that the above copyright notice appears in all   *
 * copies and that both the copyright notice and this permission notice   *
 * appear in the supporting documentation. The authors make no claims     *
 * about the suitability of this software for any purpose. It is          *
 * provided "as is" without express or implied warranty.                  *
 **************************************************************************/

/* $Id$ */

==========================================================
Please add  to this README file all information concerning 
config files, simulation, digitalization, clusterization, 
reconstruction and macro analysis

==========================================================
 How to run a MUON generation
==========================================================
aliroot
root [0] gAlice->Run(10,"$ALICE_ROOT/MUON/Config_MUON_test.C");

1 single muon of 7 GeV/c in the MUON spectrometer 
acceptance will be simulated using geant3. 
Hit information will be store in the root file in the
execution directory.
If you want to change the option or to define a new directory
for hits, you have to do the following before:
root [0] gAlice->SetConfigFunction("Config( \"/home/martinez/aliroot/work_NewIO/test/\" , \"box\" );"); 


============================================================
 How to run MUONCheck macro
============================================================
To check the content of a root data file, the MUONCheck
provides a ascii output on screen.

To compile MUONCheck.C
.includepath $ALICE_ROOT/STEER
.includepath $ALICE_ROOT/MUON
.L $ALICE_ROOT/MUON/MUONCheck.C++
To Load
gSystem->Load("$ALICE_ROOT/MUON/MUONCheck_C.so")

To print Kine : (default file is galice.root )
MUONkine() or MUONkine("galice.root",##) for the event number ##

To print hits : (default file is galice.root if not MUONhits("toto.root""); )
MUONhits()  or MUONhits("galice.root",##) for the event number ##

To print digits : (default file is galice.root)
MUONdigits()  or MUONdigits("galice.root",##) for the event number ##

To print rawcluster : (default file is galice.root)
MUONrecpoints() or MUONrecpoints("galice.root",##) for the event number ##

To print trigger : (default file is galice.root)
MUONTestTrigger() or MUONTestTrigger("galice.root",##) for the event number ##

....


============================================================
 How to check the Geometry
============================================================
gAlice->Init("$ALICE_ROOT/MUON/Config_MUON_test.C");
.L $ALICE/geant3/TGeant3/G3GUI.C
G3GUI()


============================================================
 How to run MUONdisplay
============================================================
First you need to perform a full simulation: 
generation, digitalisation and clusterisation
.L $ALICE_ROOT/MUON/MUONdisplay.C
MUONdisplay(0,"galice.root")

============================================================
 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
defined by the Config files, except for the gas mixture medium 
of the tracking chambers. The CUT's and physics processes of
the gas mixture medium  is then defined in the galice.cuts file
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.

============================================================
 Tracking of particle in the magnetic field
============================================================
GEANT has two ways for tracking charged particles in the 
magnetic field: HELIX et RKUTA.
HELIX is faster and works well if the gradient of magnetic 
field is small. 
For MUON, HELIX is a not a good approximation and we must 
use RKUTA to get the optimal mass resolution of the 
spectrometer. The choice of HELIX or RKUTA is done in the
config file when the magnetic field is defined:
  AliMagFMaps* field = new AliMagFMaps("Maps","Maps", TRACKING, FACTOR, MAXB, AliMagFMaps::k4kG);
  gAlice->SetField(field);
TRACKING must be 1 for RKUTA and 2 for HELIX (the default value for aliroot is 2 (HELIX))
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

===========================================================
 MUON cocktail for physics ..............
===========================================================
There is a MUON cocktail generator of the muon sources in the
EVGEN directory. This class derives from AliGenCocktail.
In the init of this class I have filled the cocktail with 
the muon sources: J/Psi, Upsilon, Open Charm, Open Beauty, 
Pion, Kaons. The code needs only the production cross section 
at 4pi (for the moment this values are in the code since I 
prefere them do not be modified), and the code calculates the  
rate of particles in the acceptance, making the scaling based 
on the number of collisions for the hard probes and on the  
number of participants for soft sources: Pions and Kaons.

In the Genereate of this class all entries in the cocktail 
are called and we define a "primordial trigger" with requires 
a minimum number of muons above a Pt cut in the required acceptance.
In order to normalized to the real number of simulated events, 
there are 2 data members in the class fNsuceeded adn fNGenerate 
which tell us what is the biais source.

Enclose an example to use this generator:   
AliGenMUONCocktail * gener = new AliGenMUONCocktail();
gener->SetPtRange(1.,100.);       // Transverse momentum range  
gener->SetPhiRange(0.,360.);    // Azimuthal angle range 
gener->SetYRange(-4.0,-2.4);
gener->SetMuonPtCut(1.);
gener->SetMuonThetaCut(171.,178.);
gener->SetMuonMultiplicity(2);
gener->SetNumberOfCollisions(1950.);   
gener->SetNumberOfParticipants(400.);     
gener->SetVertexSmear(kPerTrack);  
gener->SetOrigin(0,0,0);        // Vertex position
gener->SetSigma(0,0,0.0);       // Sigma in (X,Y,Z) (cm) on IP position
gener->Init();
 
===========================================================
 csh Script for the full reconstruction with raw data generator
===========================================================


aliroot -b << EOF  
AliSimulation MuonSim("YourConfig.C")
MuonSim.SetWriteRawData("MUON");
MuonSim.Run(XXX)
.q
EOF

aliroot -b << EOF 
TPluginManager* pluginManager = gROOT->GetPluginManager();
pluginManager->AddHandler("AliReconstructor", "MUON","AliMUONReconstructor", "MUON","AliMUONReconstructor()")
AliReconstruction MuonRec("galice.root") 
MuonRec.SetRunTracking("")
MuonRec.SetRunVertexFinder(kFALSE)
MuonRec.SetRunLocalReconstruction("MUON")
MuonRec.SetFillESD("MUON")
MuonRec.Run() 
.q
EOF

aliroot -b << EOF  
.includepath $ALICE_ROOT/STEER
.includepath $ALICE_ROOT/MUON
.L $ALICE_ROOT/MUON/MUONmassPlot_ESD.C++
MUONmassPlot("galice.root",0,99999);
.q
EOF


============================================================
 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 and
kinematic informations (TParticle) for the vertex.
This macro can be used to check the track reconstruction e.g. efficiency,
momentum resolution ... but also to make physics analysis whenever
track identification is needed.   

To compile MUONRecoCheck.C
.includepath $ALICE_ROOT/STEER
.includepath $ALICE_ROOT/MUON
.L $ALICE_ROOT/MUON/MUONRecoCheck.C+

// To run MUONRecoCheck
MUONRecoCheck(nEvent,"galice.root"); // nEvent = nb of events


============================================================
 How to run MUONTracker macro
============================================================
To make the track reconstruction directly from AliTrackReference hits 
which are recorded in TrackRefs.root during the simulation.
It can be used to check the reconstruction without clusterization.	

To compile MUONTracker.C
.includepath $ALICE_ROOT/STEER
.includepath $ALICE_ROOT/MUON
.L $ALICE_ROOT/MUON/MUONTracker.C+

// To run MUONTracker
MUONTracker(iEventMin,iEventMax,"galice.root"); // iEventMin: first event
						// iEventMax: last event	


===========================================================
 Still working ..............
===========================================================
Commit	Line	Data
	1	/**************************************************************************
	2	* Copyright(c) 1998-1999, ALICE Experiment at CERN, All rights reserved. *
	3	* *
	4	* Author: The ALICE Off-line Project. *
	5	* Contributors are mentioned in the code where appropriate. *
	6	* *
	7	* Permission to use, copy, modify and distribute this software and its *
	8	* documentation strictly for non-commercial purposes is hereby granted *
	9	* without fee, provided that the above copyright notice appears in all *
	10	* copies and that both the copyright notice and this permission notice *
	11	* appear in the supporting documentation. The authors make no claims *
	12	* about the suitability of this software for any purpose. It is *
	13	* provided "as is" without express or implied warranty. *
	14	**************************************************************************/
	15
	16	/* $Id$ */
	17
	18	==========================================================
	19	Please add to this README file all information concerning
	20	config files, simulation, digitalization, clusterization,
	21	reconstruction and macro analysis
	22
	23	==========================================================
	24	How to run a MUON generation
	25	==========================================================
	26	aliroot
	27	root [0] gAlice->Run(10,"$ALICE_ROOT/MUON/Config_MUON_test.C");
	28
	29	1 single muon of 7 GeV/c in the MUON spectrometer
	30	acceptance will be simulated using geant3.
	31	Hit information will be store in the root file in the
	32	execution directory.
	33	If you want to change the option or to define a new directory
	34	for hits, you have to do the following before:
	35	root [0] gAlice->SetConfigFunction("Config( \"/home/martinez/aliroot/work_NewIO/test/\" , \"box\" );");
	36
	37
	38	============================================================
	39	How to run MUONCheck macro
	40	============================================================
	41	To check the content of a root data file, the MUONCheck
	42	provides a ascii output on screen.
	43
	44	To compile MUONCheck.C
	45	.includepath $ALICE_ROOT/STEER
	46	.includepath $ALICE_ROOT/MUON
	47	.L $ALICE_ROOT/MUON/MUONCheck.C++
	48	To Load
	49	gSystem->Load("$ALICE_ROOT/MUON/MUONCheck_C.so")
	50
	51	To print Kine : (default file is galice.root )
	52	MUONkine() or MUONkine("galice.root",##) for the event number ##
	53
	54	To print hits : (default file is galice.root if not MUONhits("toto.root""); )
	55	MUONhits() or MUONhits("galice.root",##) for the event number ##
	56
	57	To print digits : (default file is galice.root)
	58	MUONdigits() or MUONdigits("galice.root",##) for the event number ##
	59
	60	To print rawcluster : (default file is galice.root)
	61	MUONrecpoints() or MUONrecpoints("galice.root",##) for the event number ##
	62
	63	To print trigger : (default file is galice.root)
	64	MUONTestTrigger() or MUONTestTrigger("galice.root",##) for the event number ##
	65
	66	....
	67
	68
	69	============================================================
	70	How to check the Geometry
	71	============================================================
	72	gAlice->Init("$ALICE_ROOT/MUON/Config_MUON_test.C");
	73	.L $ALICE/geant3/TGeant3/G3GUI.C
	74	G3GUI()
	75
	76
	77	============================================================
	78	How to run MUONdisplay
	79	============================================================
	80	First you need to perform a full simulation:
	81	generation, digitalisation and clusterisation
	82	.L $ALICE_ROOT/MUON/MUONdisplay.C
	83	MUONdisplay(0,"galice.root")
	84
	85	============================================================
	86	Tracking parameters, cuts, energy loss and physics processes
	87	============================================================
	88	Tracking parameters in MUON are automatically defined by GEANT
	89	MUON takes the default values of CUTs and physics processes
	90	defined by the Config files, except for the gas mixture medium
	91	of the tracking chambers. The CUT's and physics processes of
	92	the gas mixture medium is then defined in the galice.cuts file
	93	in the data directory. In particular ILOSS parameter MUST be
	94	equal unity (1) in order simulate a realistic energy loss
	95	distribution (mean value and fluctuations) in the active gas.
	96
	97	============================================================
	98	Tracking of particle in the magnetic field
	99	============================================================
	100	GEANT has two ways for tracking charged particles in the
	101	magnetic field: HELIX et RKUTA.
	102	HELIX is faster and works well if the gradient of magnetic
	103	field is small.
	104	For MUON, HELIX is a not a good approximation and we must
	105	use RKUTA to get the optimal mass resolution of the
	106	spectrometer. The choice of HELIX or RKUTA is done in the
	107	config file when the magnetic field is defined:
	108	AliMagFMaps* field = new AliMagFMaps("Maps","Maps", TRACKING, FACTOR, MAXB, AliMagFMaps::k4kG);
	109	gAlice->SetField(field);
	110	TRACKING must be 1 for RKUTA and 2 for HELIX (the default value for aliroot is 2 (HELIX))
	111	FACTOR allows you to set the magnetic field to 0, just putting FACTOR=0. Default value is 1.
	112	MAXB is the maximum magnetic field which is 10.T
	113
	114	===========================================================
	115	MUON cocktail for physics ..............
	116	===========================================================
	117	There is a MUON cocktail generator of the muon sources in the
	118	EVGEN directory. This class derives from AliGenCocktail.
	119	In the init of this class I have filled the cocktail with
	120	the muon sources: J/Psi, Upsilon, Open Charm, Open Beauty,
	121	Pion, Kaons. The code needs only the production cross section
	122	at 4pi (for the moment this values are in the code since I
	123	prefere them do not be modified), and the code calculates the
	124	rate of particles in the acceptance, making the scaling based
	125	on the number of collisions for the hard probes and on the
	126	number of participants for soft sources: Pions and Kaons.
	127
	128	In the Genereate of this class all entries in the cocktail
	129	are called and we define a "primordial trigger" with requires
	130	a minimum number of muons above a Pt cut in the required acceptance.
	131	In order to normalized to the real number of simulated events,
	132	there are 2 data members in the class fNsuceeded adn fNGenerate
	133	which tell us what is the biais source.
	134
	135	Enclose an example to use this generator:
	136	AliGenMUONCocktail * gener = new AliGenMUONCocktail();
	137	gener->SetPtRange(1.,100.); // Transverse momentum range
	138	gener->SetPhiRange(0.,360.); // Azimuthal angle range
	139	gener->SetYRange(-4.0,-2.4);
	140	gener->SetMuonPtCut(1.);
	141	gener->SetMuonThetaCut(171.,178.);
	142	gener->SetMuonMultiplicity(2);
	143	gener->SetNumberOfCollisions(1950.);
	144	gener->SetNumberOfParticipants(400.);
	145	gener->SetVertexSmear(kPerTrack);
	146	gener->SetOrigin(0,0,0); // Vertex position
	147	gener->SetSigma(0,0,0.0); // Sigma in (X,Y,Z) (cm) on IP position
	148	gener->Init();
	149
	150	===========================================================
	151	csh Script for the full reconstruction with raw data generator
	152	===========================================================
	153
	154
	155	aliroot -b << EOF
	156	AliSimulation MuonSim("YourConfig.C")
	157	MuonSim.SetWriteRawData("MUON");
	158	MuonSim.Run(XXX)
	159	.q
	160	EOF
	161
	162	aliroot -b << EOF
	163	TPluginManager* pluginManager = gROOT->GetPluginManager();
	164	pluginManager->AddHandler("AliReconstructor", "MUON","AliMUONReconstructor", "MUON","AliMUONReconstructor()")
	165	AliReconstruction MuonRec("galice.root")
	166	MuonRec.SetRunTracking("")
	167	MuonRec.SetRunVertexFinder(kFALSE)
	168	MuonRec.SetRunLocalReconstruction("MUON")
	169	MuonRec.SetFillESD("MUON")
	170	MuonRec.Run()
	171	.q
	172	EOF
	173
	174	aliroot -b << EOF
	175	.includepath $ALICE_ROOT/STEER
	176	.includepath $ALICE_ROOT/MUON
	177	.L $ALICE_ROOT/MUON/MUONmassPlot_ESD.C++
	178	MUONmassPlot("galice.root",0,99999);
	179	.q
	180	EOF
	181
	182
	183	============================================================
	184	How to run MUONRecoCheck macro
	185	============================================================
	186	To check the muon reconstruction by comparing the reconstructed tracks
	187	with the reference tracks made of "AliTrackReference" for the hits and
	188	kinematic informations (TParticle) for the vertex.
	189	This macro can be used to check the track reconstruction e.g. efficiency,
	190	momentum resolution ... but also to make physics analysis whenever
	191	track identification is needed.
	192
	193	To compile MUONRecoCheck.C
	194	.includepath $ALICE_ROOT/STEER
	195	.includepath $ALICE_ROOT/MUON
	196	.L $ALICE_ROOT/MUON/MUONRecoCheck.C+
	197
	198	// To run MUONRecoCheck
	199	MUONRecoCheck(nEvent,"galice.root"); // nEvent = nb of events
	200
	201
	202	============================================================
	203	How to run MUONTracker macro
	204	============================================================
	205	To make the track reconstruction directly from AliTrackReference hits
	206	which are recorded in TrackRefs.root during the simulation.
	207	It can be used to check the reconstruction without clusterization.
	208
	209	To compile MUONTracker.C
	210	.includepath $ALICE_ROOT/STEER
	211	.includepath $ALICE_ROOT/MUON
	212	.L $ALICE_ROOT/MUON/MUONTracker.C+
	213
	214	// To run MUONTracker
	215	MUONTracker(iEventMin,iEventMax,"galice.root"); // iEventMin: first event
	216	// iEventMax: last event
	217
	218
	219	===========================================================
	220	Still working ..............
	221	===========================================================