[u/mrichter/AliRoot.git] / AliGeant4 / doc / README

$Id$
-----------------------------------------------------------------

Geant4 related files in AliRoot:
================================
   AliRoot/TGeant4   - source of TGeant4 category
   AliRoot/AliGeant4 - source of AliGeant4 category
   
   AliRoot/AliGeant4/config:
             configuration scripts: 
                setup.sh, setup.csh
	     script for generating HTML documentation:
	        doc_XXc++2html.pl, doc_XXddl2html.pl, doc_XXsorthtml.pl, 
		doc_XXcategory.pl                     where XX = al, g4
	     scripts and template files for automatic generation of G4 test 
	     macros:
	        test_create.sh, test_create_in.sh, test_create_struct.sh,
		test_run.sh, test_run_in.sh, test_run_struct.sh,
		test_default_det_novis.in, test_default_det_vis.in		
		test_default_genN.in;       N = 0,1,2,3
                test_default_visN.in;	    N = 1 
             script for generation source directories with files
	     sorted in subdirectories corresponding to subcategories:
	        make_source.pl

   AliRoot/AliGeant4/doc:
             README
	     README.CodingConvention;
	     CodePrototype.html, G4CodePrototype.html - main code html pages
	          (they are not produced automatically)
             HTML directory is created here by doc_alc++2html.sh script;
	     HTML documentation of Geant4 can be created by doc_g4c++2html.pl

   AliRoot/AliGeant4/macro:
             Detector specific root and G4 macros (in detector subdirectories);
	     Examples of G4 macros:
	       alirunN.in         
	     Root macros:
               g4libs.C    - Root macro for loading G4 and AliRoot libraries	             
	       g4menu.C    - primitive GUI for instantiating TGeant4 and
	                     switching to G4 UI
   	       g4Config.C  - alternative of Config.C for G4
	      
   
Alice Geant4 related environment variables:
==========================================
  (used when code is compiled; see config/setup.sh)

  AG4_INSTALL
    the path to AliRoot/AliGeant4;

  AG4_VERSION
    the Geant4 version;
    if set: the provided Geant4 version and not the default one is set
    Deafault: unset

  AG4_VISUALIZE
    if set: the program is compiled with visualisation (default)
    Categories affected: 
       geometry, main, visualization     
    Default: set 
    
  AG4_OPACS    
    if set: the program is compiled with OPACS visualisation
    Categories affected: 
       geometry, main, visualization     
    Default: unset 

  TG4_DEBUG
    if set: checks for existence fStep, fTrack are performed in TG4StepManager 
    Categories affected: event
    Default: unset   
    

  Default setting:
  ---------------- 
  Can be set running the setup.sh script:

  . $ALICE_ROOT/AliGeant4/config/setup.sh          for zsh  users   
  source $ALICE_ROOT/AliGeant4/config/setup.csh    for tcsh users

  The setup script can be added into a user login script:
  
  for zsh  users:
  # can be added to .zshenv 
  # Alice and Geant4 default settings 
  . $ALICE_ROOT/AliGeant4/config/setup.sh    

  for tcsh users (not available yet)
  # can be added to .login
  # Alice and Geant4 default settings 
  source $ALICE_ROOT/AliGeant4/config/setup.csh     

  Supported systems: HP-aCC, Linux-g++.
  

Compilation:
============
   cd $ALICE_ROOT
   gmake geant4	


Code documentation:
===================	            
    doc_alc++2html.pl
       - perl script using Pavel Binko's ddl2html perl script
         (http://wwwinfo.cern.ch/~binko/Ddl2Html/Ddl2Html.code)
         for automatic generating of code documentation in html;
	 creates doc/HTML directory containing *.html files for all 
	 *.hh, *.ddl, *.cc, alice.mk, GNUmakefile*, alice_*.(c)sh
	 and *.html index pages according to class categories  
       - calls: doc_alddl2html.pl: modified ddl2html
                doc_alsorthtml.pl: generates html pages for class
		                   categories 
       - the main page AG4CodePrototype.html with links to category index 
         pages and the alphabetical index page was created manually			       	 

Executables:
============
   (in $ALICE_ROOT/bin/tgt_SYSTEM/)
   aliroot   - standard aliroot main;
               not linked with G4 libs, starts in Root UI;
	       !! cannot be used with all G4 GUIs
   aligeant4 - main linked with G4 libs, starts in G4 UI


   1. Interactive mode
      -----------------

   1.A. with aliroot:
   
        aliroot [Xm]
 	.x g4menu.C
	
   1.B. with aligeant4:  	     

     B.1.  aligeant4 [Xm]        
	           terminal is used for typing commands;
                   if Xm is specified Motif Window is open for typing 
		   commands 
                   !! when simple terminal used with Xo driver it may 
		   freeze the whole X server 
		   -> use A. instead of this possibility 
      
     B.2.a. java gag
	           java GAG GUI is activated; 
		   select: GEANT4 -> Execute GEANT4 
		   and select aligeant4 executable in file browser
     B.2.b  tmomo
	           Tcl/Tk Momo and GAG GUI is activated;
		   select GAG -> Function -> Run GEANT4 
		   and select aligean4 executable in file browser 	   
     B.3. aligeant4 Wo    
	           OPACS GUI is activated
		   
   2. Batch mode:	 
      -----------
      Use aliroot for running in batch mode with Root macros
      (*.C) and aligeant4 with G4 macros (*.in):
      
      aliroot    macro.C         
      aligeant4  macro.in   
      
      G4 macro "macro.in" can be called from Root macro:
      
          (TGeant4*)gMC->ProcessGeantMacro("macro.in");
	   
      Root macro "macro.C" can be called from G4 macro:
      
           /g4mc/rootMacro  macro
             
            
      Several examples of Geant4 macros for running aligeant4 in a batch mode
      are available in $ALICE_ROOT/macro:
      
          alirun0.in - the simple macro how to run with default setup
	               using g4 commands
          alirun1.in - example of interactive particle gun usage and
                       drawing trajectories;	  
	  alirun2.in - example of special lego run with calling
                       Root macro lego.C from g4 and switching to root UI
	  alirun3.in - the simple macro building PPR versions of detectors
	               (now obsolete)
	  alirun4.in - example for geometry browser usage 	       
		       

Alice Geant4 Commands:
=======================

/aliDet
  
  /aliDet/switchOn  modNameVer
     modNameVer: 
       NONE, ALL, DDD[n]      
     where
       NONE    no modules are selected (default)
       ALL     all available modules (default versions) are selected
       DDD[n]  AliRoot module DDD of n-th version is selected;
               if n is not specified the default version is selected 
       !! work only during preinit phase;
     
  /aliDet/switchOff  whichVolume
     whichVolume: 
       ALL, LV, DDD
     default value: no
     !! work only during preinit phase;

  /aliDet/list
     list of all modules currently switched on

  /aliDet/listAvailable
     list of all available modules

  /aliDet/fieldValue value
     define magnetic field in Z direction
     
  /aliDet/writeGeometry true
     generate g3calls.dat for all built AliRoot detectors  

  /aliDet/readGeometry true
     build AliRoot detectors from g3calls.dat instead of
     processing AliModule->CreateGeometry()

  /aliDet/printMaterials
     prints all materials

  /aliDet/generateXML
     generate geometry XML file

  Sub-directories /aliDet/XXX/ commands : 
    setFrame            * Set detector frame
    list                * List all logical volumes of body detector
    listLong            * List all logical volumes and number of its physical
                          volumes (daughters) that are placed in this LV
    listDaughters       * List daughters of the given logical volumes
    listLongDaughters   * List daughters of the given logical volumes
    setVolume           * Set the current logical volume.
    setVisibility       * Make body detector visible/invisible.
    setLVTreeVisibility * Make current volume tree visible/invisible.
    setVolVisibility    * Make current volume visible/invisible.
    setColour           * Set colour for all body detector volumes.
    setLVTreeColour     * Set colour for the current volume tree.
    setVolColour        * Set colour for the current volume.
    
/aliGenerator
   set primary generator action 
   /aliGenerator/set generatorName
      generatorName: 
        Gun              ->  particle gun (default)
        Geantino         ->  geantino with random momentum (default);
        GhargedGeantino  ->  charged geantino with random momentum;
        AliGenerator     ->  generator from AliRoot defined either in
	                     Config.C or interactively in Root shell			     			     
   /aliGenerator/nofParticles number
      default value: 1
      Comment: does not set nof particles for AliGenerator
               ( it has to be set by Aligenerator set method)  
   /aliGenerator/verbose verboseLevel
     verboseLevel: 0, 1, 2
          default value: 0		        

/aliGun
   build a gun of particles with given properties
   
  /aliGun/listAvailable
     list of available particles
  /aliGun/listCurrent
     list of the properties of the current gun particle, that
     can be add to the gun using addGun command
  /aliGun/particle
     set the current particle definition
  /aliGun/momentum
     set the current particle momentum 
  /aliGun/position
     set the current particle position  
  /aliGun/time
     set the current particle initial time
  /aliGun/polarization
     set the current particle polarization
  /aliGun/direction 
     set the current particle momentum direction
  /aliGun/kinEnergy
     set the current particle kinetic energy
  /aliGun/list
     list of all particles in the Alice gun
  /aliGun/addParticle      
     add the current particle to the gun
  /aliGun/removeParticle i
     remove the i-th particle from the gun
  /aliGun/reset
     remove all the particles from the gun   
     
/aliEvent        
  /aliEvent/drawTracks  drawFlag
     drawFlag:  ALL      tracks for all particles are drawn
                CHARGED  tracks for charged particles only are drawn
		NONE     no tracks are drawn
     default value: CHARGED	
  /aliEvent/verbose verboseLevel
     verboseLevel: 0   no hits information  is printed
                   1   number of hits for hits collections stored per event
		       is printed
		   2   full hits information for hits collections stored 
		       per event is printed
     default value: 0		        

/aliTracking        
  /aliTracking/verbose verboseLevel
     verboseLevel: 0   no information from AlTrackingAction is printed
                   1   each 100th primary track id is printed
                   2   each primary track id is printed    
     default value: 0		
  /aliTracking/loopVerbose loopVerboseLevel
     set tracking verbose level for detected looping tracks
     loopVerboseLevel: see /tracking/verbose
     default value: 0		

/aliRunAction
  /aliRunAction/verbose  verboseLevel
     verboseLevel: 0 - 2    no influence on output yet

/aliRun  
  redefinition of /run commands for AliRoot:
  !! /aliRun commands has to be used instead of /run commands 
     in order to perform AliRun actions, too       
  /aliRun/initialize  
  /aliRun/beamOn   nofEvent
  /aliRun/lego    
     special lego run from AliRoot
     (with default lego parameters) 
  /aliRun/setConfig
     set configuration macro name (default Config)

/g4mc 
Commands: 
   setOptical      * Set Cerenkov and optical processes.
   setHadron       * Set hadron processes.
   setSpecialCuts  * Set special cuts process.
   setSpecialFlags * Set special flags process.
   root            * Switch to Root interactive shell.
   rootMacro       * Process Root macro with given name (from file name.C)
   rootCmd         * Process Root command
   g3Defaults      * Set G3 default parameters (cut values, tracking media max 
                     step values, ...)
   setProcessActivation * Activate/inactivate physics processes
                          (for development tests only)
Commit	Line	Data
676fb573	1	$Id$
	2	-----------------------------------------------------------------
	3
2e4c6f15	4	Geant4 related files in AliRoot:
	5	================================
	6	AliRoot/TGeant4 - source of TGeant4 category
97818cd2	7	AliRoot/AliGeant4 - source of AliGeant4 category
676fb573	8
2e4c6f15	9	AliRoot/AliGeant4/config:
	10	configuration scripts:
	11	setup.sh, setup.csh
676fb573	12	script for generating HTML documentation:
	13	doc_XXc++2html.pl, doc_XXddl2html.pl, doc_XXsorthtml.pl,
	14	doc_XXcategory.pl where XX = al, g4
676fb573	15	scripts and template files for automatic generation of G4 test
	16	macros:
	17	test_create.sh, test_create_in.sh, test_create_struct.sh,
	18	test_run.sh, test_run_in.sh, test_run_struct.sh,
	19	test_default_det_novis.in, test_default_det_vis.in
	20	test_default_genN.in; N = 0,1,2,3
97818cd2	21	test_default_visN.in; N = 1
	22	script for generation source directories with files
	23	sorted in subdirectories corresponding to subcategories:
	24	make_source.pl
2e4c6f15	25
	26	AliRoot/AliGeant4/doc:
	27	README
676fb573	28	README.CodingConvention;
676fb573	29	CodePrototype.html, G4CodePrototype.html - main code html pages
2e4c6f15	30	(they are not produced automatically)
676fb573	31	HTML directory is created here by doc_alc++2html.sh script;
676fb573	32	HTML documentation of Geant4 can be created by doc_g4c++2html.pl
2e4c6f15	33
2e4c6f15	34	AliRoot/AliGeant4/macro:
97818cd2	35	Detector specific root and G4 macros (in detector subdirectories);
	36	Examples of G4 macros:
	37	alirunN.in
	38	Root macros:
	39	g4libs.C - Root macro for loading G4 and AliRoot libraries
	40	g4menu.C - primitive GUI for instantiating TGeant4 and
	41	switching to G4 UI
	42	g4Config.C - alternative of Config.C for G4
2e4c6f15	43
676fb573	44
2e4c6f15	45	Alice Geant4 related environment variables:
	46	==========================================
	47	(used when code is compiled; see config/setup.sh)
676fb573	48
676fb573	49	AG4_INSTALL
2e4c6f15	50	the path to AliRoot/AliGeant4;
676fb573	51
	52	AG4_VERSION
	53	the Geant4 version;
	54	if set: the provided Geant4 version and not the default one is set
	55	Deafault: unset
	56
	57	AG4_VISUALIZE
	58	if set: the program is compiled with visualisation (default)
	59	Categories affected:
	60	geometry, main, visualization
	61	Default: set
	62
	63	AG4_OPACS
	64	if set: the program is compiled with OPACS visualisation
	65	Categories affected:
	66	geometry, main, visualization
	67	Default: unset
	68
84eca86f	69	TG4_DEBUG
	70	if set: checks for existence fStep, fTrack are performed in TG4StepManager
	71	Categories affected: event
	72	Default: unset
676fb573	73
2e4c6f15	74
676fb573	75	Default setting:
676fb573	76	----------------
2e4c6f15	77	Can be set running the setup.sh script:
676fb573	78
2e4c6f15	79	. $ALICE_ROOT/AliGeant4/config/setup.sh for zsh users
2e4c6f15	80	source $ALICE_ROOT/AliGeant4/config/setup.csh for tcsh users
676fb573	81
2e4c6f15	82	The setup script can be added into a user login script:
676fb573	83
676fb573	84	for zsh users:
2e4c6f15	85	# can be added to .zshenv
676fb573	86	# Alice and Geant4 default settings
2e4c6f15	87	. $ALICE_ROOT/AliGeant4/config/setup.sh
676fb573	88
	89	for tcsh users (not available yet)
	90	# can be added to .login
	91	# Alice and Geant4 default settings
2e4c6f15	92	source $ALICE_ROOT/AliGeant4/config/setup.csh
	93
	94	Supported systems: HP-aCC, Linux-g++.
	95
676fb573	96
	97	Compilation:
	98	============
2e4c6f15	99	cd $ALICE_ROOT
	100	gmake geant4
	101
676fb573	102
	103	Code documentation:
	104	===================
	105	doc_alc++2html.pl
	106	- perl script using Pavel Binko's ddl2html perl script
	107	(http://wwwinfo.cern.ch/~binko/Ddl2Html/Ddl2Html.code)
	108	for automatic generating of code documentation in html;
	109	creates doc/HTML directory containing *.html files for all
	110	.hh, .ddl, .cc, alice.mk, GNUmakefile, alice_*.(c)sh
	111	and *.html index pages according to class categories
	112	- calls: doc_alddl2html.pl: modified ddl2html
	113	doc_alsorthtml.pl: generates html pages for class
	114	categories
	115	- the main page AG4CodePrototype.html with links to category index
	116	pages and the alphabetical index page was created manually
	117
2e4c6f15	118	Executables:
676fb573	119	============
2e4c6f15	120	(in $ALICE_ROOT/bin/tgt_SYSTEM/)
	121	aliroot - standard aliroot main;
	122	not linked with G4 libs, starts in Root UI;
	123	!! cannot be used with all G4 GUIs
	124	aligeant4 - main linked with G4 libs, starts in G4 UI
	125
	126
	127	1. Interactive mode
	128	-----------------
	129
	130	1.A. with aliroot:
	131
	132	aliroot [Xm]
	133	.x g4menu.C
	134
	135	1.B. with aligeant4:
	136
	137	B.1. aligeant4 [Xm]
	138	terminal is used for typing commands;
	139	if Xm is specified Motif Window is open for typing
	140	commands
	141	!! when simple terminal used with Xo driver it may
	142	freeze the whole X server
	143	-> use A. instead of this possibility
	144
	145	B.2.a. java gag
676fb573	146	java GAG GUI is activated;
676fb573	147	select: GEANT4 -> Execute GEANT4
2e4c6f15	148	and select aligeant4 executable in file browser
2e4c6f15	149	B.2.b tmomo
676fb573	150	Tcl/Tk Momo and GAG GUI is activated;
676fb573	151	select GAG -> Function -> Run GEANT4
2e4c6f15	152	and select aligean4 executable in file browser
	153	B.3. aligeant4 Wo
	154	OPACS GUI is activated
	155
	156	2. Batch mode:
	157	-----------
	158	Use aliroot for running in batch mode with Root macros
	159	(.C) and aligeant4 with G4 macros (.in):
	160
	161	aliroot macro.C
	162	aligeant4 macro.in
	163
	164	G4 macro "macro.in" can be called from Root macro:
	165
	166	(TGeant4*)gMC->ProcessGeantMacro("macro.in");
	167
	168	Root macro "macro.C" can be called from G4 macro:
	169
	170	/g4mc/rootMacro macro
	171
	172
	173	Several examples of Geant4 macros for running aligeant4 in a batch mode
	174	are available in $ALICE_ROOT/macro:
	175
	176	alirun0.in - the simple macro how to run with default setup
	177	using g4 commands
	178	alirun1.in - example of interactive particle gun usage and
	179	drawing trajectories;
	180	alirun2.in - example of special lego run with calling
	181	Root macro lego.C from g4 and switching to root UI
4a553db8	182	alirun3.in - the simple macro building PPR versions of detectors
	183	(now obsolete)
	184	alirun4.in - example for geometry browser usage
2e4c6f15	185
	186
	187	Alice Geant4 Commands:
	188	=======================
676fb573	189
	190	/aliDet
	191
	192	/aliDet/switchOn modNameVer
	193	modNameVer:
	194	NONE, ALL, DDD[n]
	195	where
	196	NONE no modules are selected (default)
	197	ALL all available modules (default versions) are selected
	198	DDD[n] AliRoot module DDD of n-th version is selected;
	199	if n is not specified the default version is selected
	200	!! work only during preinit phase;
	201
	202	/aliDet/switchOff whichVolume
	203	whichVolume:
	204	ALL, LV, DDD
	205	default value: no
	206	!! work only during preinit phase;
	207
	208	/aliDet/list
2e4c6f15	209	list of all modules currently switched on
676fb573	210
2e4c6f15	211	/aliDet/listAvailable
2e4c6f15	212	list of all available modules
676fb573	213
2e4c6f15	214	/aliDet/fieldValue value
	215	define magnetic field in Z direction
	216
676fb573	217	/aliDet/writeGeometry true
	218	generate g3calls.dat for all built AliRoot detectors
	219
	220	/aliDet/readGeometry true
	221	build AliRoot detectors from g3calls.dat instead of
	222	processing AliModule->CreateGeometry()
2e4c6f15	223
97818cd2	224	/aliDet/printMaterials
	225	prints all materials
	226
	227	/aliDet/generateXML
	228	generate geometry XML file
	229
2e4c6f15	230	Sub-directories /aliDet/XXX/ commands :
	231	setFrame * Set detector frame
	232	list * List all logical volumes of body detector
	233	listLong * List all logical volumes and number of its physical
	234	volumes (daughters) that are placed in this LV
	235	listDaughters * List daughters of the given logical volumes
	236	listLongDaughters * List daughters of the given logical volumes
	237	setVolume * Set the current logical volume.
	238	setVisibility * Make body detector visible/invisible.
	239	setLVTreeVisibility * Make current volume tree visible/invisible.
	240	setVolVisibility * Make current volume visible/invisible.
	241	setColour * Set colour for all body detector volumes.
	242	setLVTreeColour * Set colour for the current volume tree.
	243	setVolColour * Set colour for the current volume.
2e4c6f15	244
676fb573	245	/aliGenerator
	246	set primary generator action
	247	/aliGenerator/set generatorName
	248	generatorName:
	249	Gun -> particle gun (default)
	250	Geantino -> geantino with random momentum (default);
	251	GhargedGeantino -> charged geantino with random momentum;
676fb573	252	AliGenerator -> generator from AliRoot defined either in
	253	Config.C or interactively in Root shell
	254	/aliGenerator/nofParticles number
	255	default value: 1
	256	Comment: does not set nof particles for AliGenerator
	257	( it has to be set by Aligenerator set method)
	258	/aliGenerator/verbose verboseLevel
	259	verboseLevel: 0, 1, 2
	260	default value: 0
	261
	262	/aliGun
97818cd2	263	build a gun of particles with given properties
676fb573	264
	265	/aliGun/listAvailable
	266	list of available particles
	267	/aliGun/listCurrent
	268	list of the properties of the current gun particle, that
	269	can be add to the gun using addGun command
	270	/aliGun/particle
	271	set the current particle definition
	272	/aliGun/momentum
	273	set the current particle momentum
	274	/aliGun/position
	275	set the current particle position
	276	/aliGun/time
	277	set the current particle initial time
	278	/aliGun/polarization
	279	set the current particle polarization
	280	/aliGun/direction
	281	set the current particle momentum direction
	282	/aliGun/kinEnergy
	283	set the current particle kinetic energy
	284	/aliGun/list
	285	list of all particles in the Alice gun
	286	/aliGun/addParticle
	287	add the current particle to the gun
	288	/aliGun/removeParticle i
	289	remove the i-th particle from the gun
	290	/aliGun/reset
	291	remove all the particles from the gun
	292
	293	/aliEvent
2e4c6f15	294	/aliEvent/drawTracks drawFlag
	295	drawFlag: ALL tracks for all particles are drawn
	296	CHARGED tracks for charged particles only are drawn
	297	NONE no tracks are drawn
	298	default value: CHARGED
676fb573	299	/aliEvent/verbose verboseLevel
	300	verboseLevel: 0 no hits information is printed
	301	1 number of hits for hits collections stored per event
	302	is printed
	303	2 full hits information for hits collections stored
	304	per event is printed
	305	default value: 0
676fb573	306
	307	/aliTracking
	308	/aliTracking/verbose verboseLevel
	309	verboseLevel: 0 no information from AlTrackingAction is printed
	310	1 each 100th primary track id is printed
	311	2 each primary track id is printed
	312	default value: 0
2e4c6f15	313	/aliTracking/loopVerbose loopVerboseLevel
	314	set tracking verbose level for detected looping tracks
	315	loopVerboseLevel: see /tracking/verbose
	316	default value: 0
676fb573	317
	318	/aliRunAction
	319	/aliRunAction/verbose verboseLevel
	320	verboseLevel: 0 - 2 no influence on output yet
	321
	322	/aliRun
	323	redefinition of /run commands for AliRoot:
2e4c6f15	324	!! /aliRun commands has to be used instead of /run commands
2e4c6f15	325	in order to perform AliRun actions, too
676fb573	326	/aliRun/initialize
676fb573	327	/aliRun/beamOn nofEvent
676fb573	328	/aliRun/lego
	329	special lego run from AliRoot
	330	(with default lego parameters)
97818cd2	331	/aliRun/setConfig
97818cd2	332	set configuration macro name (default Config)
676fb573	333
2e4c6f15	334	/g4mc
	335	Commands:
	336	setOptical * Set Cerenkov and optical processes.
	337	setHadron * Set hadron processes.
	338	setSpecialCuts * Set special cuts process.
	339	setSpecialFlags * Set special flags process.
	340	root * Switch to Root interactive shell.
	341	rootMacro * Process Root macro with given name (from file name.C)
	342	rootCmd * Process Root command
	343	g3Defaults * Set G3 default parameters (cut values, tracking media max
	344	step values, ...)
	345	setProcessActivation * Activate/inactivate physics processes
	346	(for development tests only)