[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 MUON Hits to SDigits
============================================================
.L ALICE_ROOT/MUON/MUONHit2SDigit.C
MUONHit2SDigit(0,99999,"galice.root")


============================================================
 How to run MUON Digitalization from SDigits
============================================================
To process the digitalization of hits the AliRunDigitizer 
framework is used:

AliRunDigitizer   * manager = new AliRunDigitizer(1,1);
manager->SetInputStream(0,"galice.root");
AliMUONDigitizerv2* dMUON   = new AliMUONDigitizerv2(manager)
manager->AddDigitizer(dMUON);
manager->Exec("deb");


============================================================
 How to run MUON Digitalization from Hits
============================================================
To process the digitalization of hits the AliRunDigitizer 
framework is used:

AliRunDigitizer   * manager = new AliRunDigitizer(1,1);
manager->SetInputStream(0,"galice.root");
AliMUONDigitizerv1* dMUON   = new AliMUONDigitizerv1(manager)
manager->AddDigitizer(dMUON);
manager->Exec("deb");

============================================================
 How to run MUON RecPoint clusterization
============================================================
aliroot -b << EOF
.includepath $ALICE_ROOT/STEER
.includepath $ALICE_ROOT/MUON
.L $ALICE_ROOT/MUON/MUONrawclusters.C++
MUONrawclusters("galice.root",0,9999); 
to Load
gSystem->Load("$ALICE_ROOT/MUON/MUONrawclusters_C.so")

============================================================
 How to run MUON Trigger
============================================================
.includepath $ALICE_ROOT/STEER
.includepath $ALICE_ROOT/MUON
.L $ALICE_ROOT/MUON/MUONtrigger.C++
MUONtrigger("galice.root",0,9999); 
To Load
gSystem->Load("$ALICE_ROOT/MUON/MUONtrigger_C.so")

============================================================
 How to run MUON Tracking reconstruction (old output)
===========================================================
.includepath $ALICE_ROOT/STEER
.includepath $ALICE_ROOT/MUON
.L $ALICE_ROOT/MUON/MUONrecoNtuple.C++
MUONrecoNtuple(0,9999,0,"galice.root") 
To Load   
gSystem->Load("$ALICE_ROOT/MUON/MUONrecoNtuple_C.so")
First event and last event are given by hand, but this will change.

===========================================================
 How to run MUON Tracking reconstruction (new output)
===========================================================
.includepath $ALICE_ROOT/STEER
.includepath $ALICE_ROOT/MUON
.L $ALICE_ROOT/MUON/MUONTracker.C++
MUONTracker("galice.root",0,9999);    
To Load
gSystem->Load("$ALICE_ROOT/MUON/MUONTracker_C.so")
Output in MUON.Tracks.root using the new IO 
as a TClonesArray of AliMUONTrack

Note1.In the actual version (dec-03) the following data 
members  of ALiMUONTrack:  fgFitter, fEventReconstructor, 
and fTrackHitsPtr are not saved in the MUON.Track.root file


===========================================================
 How to run MUON Trigger Track reconstruction (new output)
===========================================================
.includepath $ALICE_ROOT/STEER
.includepath $ALICE_ROOT/MUON
.L $ALICE_ROOT/MUON/MUONTriggerTracker.C++
MUONTriggerTracker("galice.root",0,10);    
To Load
gSystem->Load("$ALICE_ROOT/MUON/MUONTriggerTracker_C.so")
Output in MUON.Tracks.root using the new IO 
as a TClonesArray of AliMUONTriggerTrack

==========================================================
 How to run full MUON  reconstruction 
(clusterisation + trigger + tracking)
===========================================================
.includepath $ALICE_ROOT/STEER
.includepath $ALICE_ROOT/MUON
.L $ALICE_ROOT/MUON/MUONChallengeTest.C++
MUONRecoTest("galice.root");


============================================================
 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
===========================================================
aliroot -b << EOF  
gAlice->Run(NumberOfEvents,"YourConfig.C");
.q
EOF

aliroot -b << EOF
.L ALICE_ROOT/MUON/MUONHit2SDigit.C
MUONHit2SDigit(0,99999,"galice.root")
.q
EOF


aliroot -b << EOF
AliRunDigitizer   * manager = new AliRunDigitizer(1,1);
manager->SetInputStream(0,"galice.root");
AliMUONDigitizerv2* dMUON   = new AliMUONDigitizerv2(manager);
manager->AddDigitizer(dMUON);
manager->Exec("deb");
.q
EOF

aliroot -b << EOF
.includepath $ALICE_ROOT/STEER
.includepath $ALICE_ROOT/MUON
.L $ALICE_ROOT/MUON/MUONChallengeTest.C++
MUONRecoTest("galice.root");
.q
EOF


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

===========================================================
 Still working ..............
===========================================================
Commit	Line	Data
50837721	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
88cb7938	18	==========================================================
	19	Please add to this README file all information concerning
	20	config files, simulation, digitalization, clusterization,
	21	reconstruction and macro analysis
	22
	23	==========================================================
7985603c	24	How to run a MUON generation
88cb7938	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.
88cb7938	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	============================================================
9f532ceb	38	How to run MUON Hits to SDigits
	39	============================================================
	40	.L ALICE_ROOT/MUON/MUONHit2SDigit.C
	41	MUONHit2SDigit(0,99999,"galice.root")
	42
	43
	44	============================================================
	45	How to run MUON Digitalization from SDigits
	46	============================================================
	47	To process the digitalization of hits the AliRunDigitizer
	48	framework is used:
	49
	50	AliRunDigitizer * manager = new AliRunDigitizer(1,1);
	51	manager->SetInputStream(0,"galice.root");
	52	AliMUONDigitizerv2* dMUON = new AliMUONDigitizerv2(manager)
	53	manager->AddDigitizer(dMUON);
	54	manager->Exec("deb");
	55
	56
	57	============================================================
	58	How to run MUON Digitalization from Hits
88cb7938	59	============================================================
	60	To process the digitalization of hits the AliRunDigitizer
	61	framework is used:
	62
2058bf30	63	AliRunDigitizer * manager = new AliRunDigitizer(1,1);
2058bf30	64	manager->SetInputStream(0,"galice.root");
e6dd99fc	65	AliMUONDigitizerv1* dMUON = new AliMUONDigitizerv1(manager)
2058bf30	66	manager->AddDigitizer(dMUON);
2058bf30	67	manager->Exec("deb");
88cb7938	68
	69	============================================================
	70	How to run MUON RecPoint clusterization
	71	============================================================
	72	aliroot -b << EOF
278a86d5	73	.includepath $ALICE_ROOT/STEER
	74	.includepath $ALICE_ROOT/MUON
	75	.L $ALICE_ROOT/MUON/MUONrawclusters.C++
bf17dbfd	76	MUONrawclusters("galice.root",0,9999);
	77	to Load
	78	gSystem->Load("$ALICE_ROOT/MUON/MUONrawclusters_C.so")
88cb7938	79
88cb7938	80	============================================================
	81	How to run MUON Trigger
	82	============================================================
ba9436c6	83	.includepath $ALICE_ROOT/STEER
	84	.includepath $ALICE_ROOT/MUON
	85	.L $ALICE_ROOT/MUON/MUONtrigger.C++
bf17dbfd	86	MUONtrigger("galice.root",0,9999);
50837721	87	To Load
50837721	88	gSystem->Load("$ALICE_ROOT/MUON/MUONtrigger_C.so")
2b32c661	89
88cb7938	90	============================================================
dcd2690d	91	How to run MUON Tracking reconstruction (old output)
fb76e306	92	===========================================================
2058bf30	93	.includepath $ALICE_ROOT/STEER
	94	.includepath $ALICE_ROOT/MUON
	95	.L $ALICE_ROOT/MUON/MUONrecoNtuple.C++
50837721	96	MUONrecoNtuple(0,9999,0,"galice.root")
	97	To Load
	98	gSystem->Load("$ALICE_ROOT/MUON/MUONrecoNtuple_C.so")
88cb7938	99	First event and last event are given by hand, but this will change.
88cb7938	100
dcd2690d	101	===========================================================
	102	How to run MUON Tracking reconstruction (new output)
	103	===========================================================
	104	.includepath $ALICE_ROOT/STEER
	105	.includepath $ALICE_ROOT/MUON
	106	.L $ALICE_ROOT/MUON/MUONTracker.C++
bf17dbfd	107	MUONTracker("galice.root",0,9999);
50837721	108	To Load
50837721	109	gSystem->Load("$ALICE_ROOT/MUON/MUONTracker_C.so")
dcd2690d	110	Output in MUON.Tracks.root using the new IO
	111	as a TClonesArray of AliMUONTrack
	112
374ebd7d	113	Note1.In the actual version (dec-03) the following data
	114	members of ALiMUONTrack: fgFitter, fEventReconstructor,
	115	and fTrackHitsPtr are not saved in the MUON.Track.root file
	116
9f532ceb	117
a3448039	118	===========================================================
	119	How to run MUON Trigger Track reconstruction (new output)
	120	===========================================================
	121	.includepath $ALICE_ROOT/STEER
	122	.includepath $ALICE_ROOT/MUON
	123	.L $ALICE_ROOT/MUON/MUONTriggerTracker.C++
	124	MUONTriggerTracker("galice.root",0,10);
	125	To Load
	126	gSystem->Load("$ALICE_ROOT/MUON/MUONTriggerTracker_C.so")
	127	Output in MUON.Tracks.root using the new IO
	128	as a TClonesArray of AliMUONTriggerTrack
	129
9f532ceb	130	==========================================================
	131	How to run full MUON reconstruction
	132	(clusterisation + trigger + tracking)
	133	===========================================================
	134	.includepath $ALICE_ROOT/STEER
	135	.includepath $ALICE_ROOT/MUON
	136	.L $ALICE_ROOT/MUON/MUONChallengeTest.C++
	137	MUONRecoTest("galice.root");
	138
a3448039	139
88cb7938	140	============================================================
	141	How to run MUONCheck macro
	142	============================================================
	143	To check the content of a root data file, the MUONCheck
	144	provides a ascii output on screen.
	145
	146	To compile MUONCheck.C
2058bf30	147	.includepath $ALICE_ROOT/STEER
	148	.includepath $ALICE_ROOT/MUON
	149	.L $ALICE_ROOT/MUON/MUONCheck.C++
bf17dbfd	150	To Load
bf17dbfd	151	gSystem->Load("$ALICE_ROOT/MUON/MUONCheck_C.so")
2058bf30	152
278a86d5	153	To print Kine : (default file is galice.root )
2b32c661	154	MUONkine() or MUONkine("galice.root",##) for the event number ##
88cb7938	155
88cb7938	156	To print hits : (default file is galice.root if not MUONhits("toto.root""); )
2b32c661	157	MUONhits() or MUONhits("galice.root",##) for the event number ##
88cb7938	158
88cb7938	159	To print digits : (default file is galice.root)
2b32c661	160	MUONdigits() or MUONdigits("galice.root",##) for the event number ##
88cb7938	161
88cb7938	162	To print rawcluster : (default file is galice.root)
2b32c661	163	MUONrecpoints() or MUONrecpoints("galice.root",##) for the event number ##
88cb7938	164
88cb7938	165	To print trigger : (default file is galice.root)
2b32c661	166	MUONTestTrigger() or MUONTestTrigger("galice.root",##) for the event number ##
	167
	168	....
88cb7938	169
02d8f072	170
	171	============================================================
	172	How to check the Geometry
	173	============================================================
	174	gAlice->Init("$ALICE_ROOT/MUON/Config_MUON_test.C");
	175	.L $ALICE/geant3/TGeant3/G3GUI.C
	176	G3GUI()
	177
	178
7985603c	179	============================================================
	180	How to run MUONdisplay
	181	============================================================
1eccde20	182	First you need to perform a full simulation:
7985603c	183	generation, digitalisation and clusterisation
	184	.L $ALICE_ROOT/MUON/MUONdisplay.C
	185	MUONdisplay(0,"galice.root")
	186
02d8f072	187	============================================================
	188	Tracking parameters, cuts, energy loss and physics processes
	189	============================================================
	190	Tracking parameters in MUON are automatically defined by GEANT
	191	MUON takes the default values of CUTs and physics processes
	192	defined by the Config files, except for the gas mixture medium
	193	of the tracking chambers. The CUT's and physics processes of
	194	the gas mixture medium is then defined in the galice.cuts file
	195	in the data directory. In particular ILOSS parameter MUST be
	196	equal unity (1) in order simulate a realistic energy loss
	197	distribution (mean value and fluctuations) in the active gas.
a88eb0d0	198
	199	============================================================
	200	Tracking of particle in the magnetic field
	201	============================================================
	202	GEANT has two ways for tracking charged particles in the
	203	magnetic field: HELIX et RKUTA.
	204	HELIX is faster and works well if the gradient of magnetic
	205	field is small.
	206	For MUON, HELIX is a not a good approximation and we must
	207	use RKUTA to get the optimal mass resolution of the
	208	spectrometer. The choice of HELIX or RKUTA is done in the
	209	config file when the magnetic field is defined:
	210	AliMagFMaps* field = new AliMagFMaps("Maps","Maps", TRACKING, FACTOR, MAXB, AliMagFMaps::k4kG);
	211	gAlice->SetField(field);
	212	TRACKING must be 1 for RKUTA and 2 for HELIX (the default value for aliroot is 2 (HELIX))
	213	FACTOR allows you to set the magnetic field to 0, just putting FACTOR=0. Default value is 1.
	214	MAXB is the maximum magnetic field which is 10.T
2b32c661	215
f4f795ed	216	===========================================================
	217	MUON cocktail for physics ..............
	218	===========================================================
	219	There is a MUON cocktail generator of the muon sources in the
	220	EVGEN directory. This class derives from AliGenCocktail.
	221	In the init of this class I have filled the cocktail with
	222	the muon sources: J/Psi, Upsilon, Open Charm, Open Beauty,
	223	Pion, Kaons. The code needs only the production cross section
	224	at 4pi (for the moment this values are in the code since I
	225	prefere them do not be modified), and the code calculates the
	226	rate of particles in the acceptance, making the scaling based
	227	on the number of collisions for the hard probes and on the
	228	number of participants for soft sources: Pions and Kaons.
	229
	230	In the Genereate of this class all entries in the cocktail
	231	are called and we define a "primordial trigger" with requires
	232	a minimum number of muons above a Pt cut in the required acceptance.
	233	In order to normalized to the real number of simulated events,
	234	there are 2 data members in the class fNsuceeded adn fNGenerate
	235	which tell us what is the biais source.
	236
	237	Enclose an example to use this generator:
	238	AliGenMUONCocktail * gener = new AliGenMUONCocktail();
	239	gener->SetPtRange(1.,100.); // Transverse momentum range
	240	gener->SetPhiRange(0.,360.); // Azimuthal angle range
	241	gener->SetYRange(-4.0,-2.4);
	242	gener->SetMuonPtCut(1.);
	243	gener->SetMuonThetaCut(171.,178.);
	244	gener->SetMuonMultiplicity(2);
	245	gener->SetNumberOfCollisions(1950.);
	246	gener->SetNumberOfParticipants(400.);
	247	gener->SetVertexSmear(kPerTrack);
	248	gener->SetOrigin(0,0,0); // Vertex position
	249	gener->SetSigma(0,0,0.0); // Sigma in (X,Y,Z) (cm) on IP position
	250	gener->Init();
	251
2b32c661	252	===========================================================
	253	csh Script for the full reconstruction
	254	===========================================================
	255	aliroot -b << EOF
	256	gAlice->Run(NumberOfEvents,"YourConfig.C");
	257	.q
	258	EOF
	259
9f532ceb	260	aliroot -b << EOF
	261	.L ALICE_ROOT/MUON/MUONHit2SDigit.C
	262	MUONHit2SDigit(0,99999,"galice.root")
	263	.q
	264	EOF
	265
	266
	267	aliroot -b << EOF
2b32c661	268	AliRunDigitizer * manager = new AliRunDigitizer(1,1);
2b32c661	269	manager->SetInputStream(0,"galice.root");
9f532ceb	270	AliMUONDigitizerv2* dMUON = new AliMUONDigitizerv2(manager);
2b32c661	271	manager->AddDigitizer(dMUON);
	272	manager->Exec("deb");
	273	.q
	274	EOF
	275
9f532ceb	276	aliroot -b << EOF
2b32c661	277	.includepath $ALICE_ROOT/STEER
2b32c661	278	.includepath $ALICE_ROOT/MUON
9f532ceb	279	.L $ALICE_ROOT/MUON/MUONChallengeTest.C++
9f532ceb	280	MUONRecoTest("galice.root");
2b32c661	281	.q
	282	EOF
	283
2b32c661	284
	285	aliroot -b << EOF
	286	.includepath $ALICE_ROOT/STEER
	287	.includepath $ALICE_ROOT/MUON
	288	.L $ALICE_ROOT/MUON/MUONmassPlot_NewIO.C++
	289	MUONmassPlot("galice.root",0,99999);
	290	.q
	291	EOF
a88eb0d0	292
88cb7938	293	===========================================================
	294	Still working ..............
	295	===========================================================