removed options ALICE_STACKING, ALICE_EMPTY_PHYSICS_LIST
[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   TG4_DEBUG
70     if set: checks for existence fStep, fTrack are performed in TG4StepManager 
71     Categories affected: event
72     Default: unset   
73     
74
75   Default setting:
76   ---------------- 
77   Can be set running the setup.sh script:
78
79   . $ALICE_ROOT/AliGeant4/config/setup.sh          for zsh  users   
80   source $ALICE_ROOT/AliGeant4/config/setup.csh    for tcsh users
81
82   The setup script can be added into a user login script:
83   
84   for zsh  users:
85   # can be added to .zshenv 
86   # Alice and Geant4 default settings 
87   . $ALICE_ROOT/AliGeant4/config/setup.sh    
88
89   for tcsh users (not available yet)
90   # can be added to .login
91   # Alice and Geant4 default settings 
92   source $ALICE_ROOT/AliGeant4/config/setup.csh     
93
94   Supported systems: HP-aCC, Linux-g++.
95   
96
97 Compilation:
98 ============
99    cd $ALICE_ROOT
100    gmake geant4 
101
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
118 Executables:
119 ============
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
146                    java GAG GUI is activated; 
147                    select: GEANT4 -> Execute GEANT4 
148                    and select aligeant4 executable in file browser
149      B.2.b  tmomo
150                    Tcl/Tk Momo and GAG GUI is activated;
151                    select GAG -> Function -> Run GEANT4 
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
182                        
183
184 Alice Geant4 Commands:
185 =======================
186
187 /aliDet
188   
189   /aliDet/switchOn  modNameVer
190      modNameVer: 
191        NONE, ALL, DDD[n]      
192      where
193        NONE    no modules are selected (default)
194        ALL     all available modules (default versions) are selected
195        DDD[n]  AliRoot module DDD of n-th version is selected;
196                if n is not specified the default version is selected 
197        !! work only during preinit phase;
198      
199   /aliDet/switchOff  whichVolume
200      whichVolume: 
201        ALL, LV, DDD
202      default value: no
203      !! work only during preinit phase;
204
205   /aliDet/list
206      list of all modules currently switched on
207
208   /aliDet/listAvailable
209      list of all available modules
210
211   /aliDet/fieldValue value
212      define magnetic field in Z direction
213      
214   /aliDet/setAllSensitive bool
215      if true: all logical volumes are associated with sensitive
216               detectors
217      if false: only volumes defined with asensitive tracking
218                medium are associated with sensitive detectors
219      It has lower priority than individual module setting
220                
221   /aliDet/forceAllSensitive
222      If true: force to set all logical volumes sensitive.
223          (Each logical is volume associated with a sensitive
224           detector.)
225      It has higher priority than individual module setting
226
227   /aliDet/writeGeometry true
228      generate g3calls.dat for all built AliRoot detectors  
229
230   /aliDet/readGeometry true
231      build AliRoot detectors from g3calls.dat instead of
232      processing AliModule->CreateGeometry()
233
234   /aliDet/printMaterials
235      prints all materials
236
237   /aliDet/generateXML
238      generate geometry XML file
239
240   Sub-directories /aliDet/XXX/ commands : 
241     setFrame            * Set detector frame
242     list                * List all logical volumes of body detector
243     listLong            * List all logical volumes and number of its physical
244                           volumes (daughters) that are placed in this LV
245     listDaughters       * List daughters of the given logical volumes
246     listLongDaughters   * List daughters of the given logical volumes
247     setVolume           * Set the current logical volume.
248     setVisibility       * Make body detector visible/invisible.
249     setLVTreeVisibility * Make current volume tree visible/invisible.
250     setVolVisibility    * Make current volume visible/invisible.
251     setColour           * Set colour for all body detector volumes.
252     setLVTreeColour     * Set colour for the current volume tree.
253     setVolColour        * Set colour for the current volume.
254     setAllSensitive     * If true: set all module's logical volumes sensitive.
255     
256 /aliGenerator
257    set primary generator action 
258    /aliGenerator/set generatorName
259       generatorName: 
260         Gun              ->  particle gun (default)
261         Geantino         ->  geantino with random momentum (default);
262         GhargedGeantino  ->  charged geantino with random momentum;
263         AliGenerator     ->  generator from AliRoot defined either in
264                              Config.C or interactively in Root shell                                                 
265    /aliGenerator/nofParticles number
266       default value: 1
267       Comment: does not set nof particles for AliGenerator
268                ( it has to be set by Aligenerator set method)  
269    /aliGenerator/verbose verboseLevel
270      verboseLevel: 0, 1, 2
271           default value: 0                      
272
273 /aliGun
274    build a gun of particles with given properties
275    
276   /aliGun/listAvailable
277      list of available particles
278   /aliGun/listCurrent
279      list of the properties of the current gun particle, that
280      can be add to the gun using addGun command
281   /aliGun/particle
282      set the current particle definition
283   /aliGun/momentum
284      set the current particle momentum 
285   /aliGun/position
286      set the current particle position  
287   /aliGun/time
288      set the current particle initial time
289   /aliGun/polarization
290      set the current particle polarization
291   /aliGun/direction 
292      set the current particle momentum direction
293   /aliGun/kinEnergy
294      set the current particle kinetic energy
295   /aliGun/list
296      list of all particles in the Alice gun
297   /aliGun/addParticle      
298      add the current particle to the gun
299   /aliGun/removeParticle i
300      remove the i-th particle from the gun
301   /aliGun/reset
302      remove all the particles from the gun   
303      
304 /aliEvent        
305   /aliEvent/drawTracks  drawFlag
306      drawFlag:  ALL      tracks for all particles are drawn
307                 CHARGED  tracks for charged particles only are drawn
308                 NONE     no tracks are drawn
309      default value: CHARGED     
310   /aliEvent/verbose verboseLevel
311      verboseLevel: 0   no hits information  is printed
312                    1   number of hits for hits collections stored per event
313                        is printed
314                    2   full hits information for hits collections stored 
315                        per event is printed
316      default value: 0                   
317
318 /aliTracking        
319   /aliTracking/verbose verboseLevel
320      verboseLevel: 0   no information from AlTrackingAction is printed
321                    1   each 100th primary track id is printed
322                    2   each primary track id is printed    
323      default value: 0           
324   /aliTracking/loopVerbose loopVerboseLevel
325      set tracking verbose level for detected looping tracks
326      loopVerboseLevel: see /tracking/verbose
327      default value: 0           
328
329 /aliRunAction
330   /aliRunAction/verbose  verboseLevel
331      verboseLevel: 0 - 2    no influence on output yet
332
333 /aliRun  
334   redefinition of /run commands for AliRoot:
335   !! /aliRun commands has to be used instead of /run commands 
336      in order to perform AliRun actions, too       
337   /aliRun/initialize  
338   /aliRun/beamOn   nofEvent
339   /aliRun/lego    
340      special lego run from AliRoot
341      (with default lego parameters) 
342   /aliRun/setConfig
343      set configuration macro name (default Config)
344
345 /g4mc 
346 Commands: 
347    setOptical      * Set Cerenkov and optical processes.
348    setHadron       * Set hadron processes.
349    setSpecialCuts  * Set special cuts process.
350    setSpecialFlags * Set special flags process.
351    root            * Switch to Root interactive shell.
352    rootMacro       * Process Root macro with given name (from file name.C)
353    rootCmd         * Process Root command
354    g3Defaults      * Set G3 default parameters (cut values, tracking media max 
355                      step values, ...)
356    setProcessActivation * Activate/inactivate physics processes
357                           (for development tests only)