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