Import Geant4 10.0.0 source tree

examples/basic/B4/README

@@ -1,4 +1,4 @@
-$Id$
+$Id: README 78001 2013-12-02 08:24:53Z gcosmo $
 -------------------------------------------------------------------
 
      =========================================================
@@ -15,6 +15,7 @@ $Id$
 	
  1- GEOMETRY DEFINITION
  
+   The geometry is constructed in B4[c,d]DetectorConstruction class.
    The calorimeter is a box made of a given number of layers. A layer
    consists of an absorber plate and of a detection gap. The layer is
    replicated.
@@ -25,11 +26,13 @@ $Id$
  	- the number of layers, and
  	- the transverse size of the calorimeter (the entrance face is a square). 
  	
-   In addition a transverse uniform magnetic field can be applied and set 
-   via the interactive command defined using the G4GenericMessenger class.
+   In addition, a global, uniform, and transverse magnetic field can be 
+   applied using G4GlobalMagFieldMessenger, instantiated in 
+     B4[c,d]DetectorConstruction::ConstructSDandField 
+   with a non zero field value, or via interactive commands. 
    For example:
 
-     /B4/det/setMagField 0.2 tesla
+   /globalField/setValue 0.2 0 0 tesla
 
 
 	|<----layer 0---------->|<----layer 1---------->|<----layer 2---------->|
@@ -63,7 +66,23 @@ $Id$
                /process/(in)activate processName
    allows to activate/inactivate the processes one by one.
  	 
- 3- PRIMARY GENERATOR
+ 3- ACTION INITALIZATION
+
+   A newly introduced class, B4[a,b,c,d]ActionInitialization, 
+   instantiates and registers to Geant4 kernel all user action classes.
+   
+   While in sequential mode the action classes are instatiated just once,
+   via invoking the method:
+      B4[a,b,c,d]ActionInitialization::Build() 
+   in multi-threading mode the same method is invoked for each thread worker
+   and so all user action classes are defined thread-local.
+
+   A run action class is instantiated both thread-local 
+   and global that's why its instance is created also in the method
+      B4[a,b,c,d]ActionInitialization::BuildForMaster()
+   which is invoked only in multi-threading mode.
+
+ 4- PRIMARY GENERATOR
  
    The primary beam consists of a single particle which hits the
    calorimeter perpendicular to the input face. The type of the particle
@@ -71,17 +90,15 @@ $Id$
    be changed via the G4 built-in commands of the G4ParticleGun class (see
    the macros provided with this example).
  	
- 4- RUNS and EVENTS
+ 5- RUNS and EVENTS
  
    A run is a set of events. 
-   
-   The user can choose the frequency of printing from B4aEventAction (or event 
-   action classes in other options) via the interactive command defined
-   using the G4GenericMessenger class, for example:
+   The user can choose the frequency of printing via the Geant4 interactive 
+   command, for example:
     
-     /B4/event/setPrintModulo 100
+     /run/printProgress 100
    
- 5- DETECTOR RESPONSE
+ 6- DETECTOR RESPONSE
  
    The energy deposit and track lengths of the charged particles are recorded on
    an event by event basis in the Absober and Gap layers.
@@ -103,8 +120,8 @@ $Id$
    Variant b: User data object 
    
      In order to avoid dependencies between action classes, a user object
-     B4bRunData is defined with data members needed to the accounted
-     information. 
+     B4bRunData, derived from G4Run, is defined with data members needed 
+     for the accounted information. 
      In order to reduce the number of data members a 2-dimensions array
      is introduced for each quantity.
      Then the quantities are collected step by step in user action classes:
@@ -117,7 +134,7 @@ $Id$
      and sensitive detectors framework defined in the Geant4 kernel.  
      The physics quantities are stored in B4cCalorHit via two B4cCalorimeterSD
      objects, one associated with the Absorber volume and another one with Gap
-     in B4cDetectorConstruction.
+     in B4cDetectorConstruction::ConstructSDandField().
      
      In contrary to the B2 example (Tracker) where a new hit is created
      with each track passing the sensitive volume (in the calorimeter), only one
@@ -134,12 +151,12 @@ $Id$
      detector classes but rather uses the classes already defined
      in Geant4. In this example, the G4MultiFunctionalDetector with
      G4PSEnergyDeposit and G4PSTrackLength primitive scores are used (see
-     B4dDetectorConstruction class).
+     B4dDetectorConstruction::ConstructSDandField()).
     
      Also with this approach, the quantities per each layer are available 
      in addition to the total quantities.
        
-  6- HISTOGRAMS
+  7- HISTOGRAMS
  
    The analysis tools are used to accumulate statistics and compute the dispersion
    of the energy deposit and track lengths of the charged particles.
@@ -156,8 +173,11 @@ $Id$
 
    The accumulated statistic and computed dispersion is printed at the end of 
    run, in B4RunAction::EndOfRunAction().
-   
-  7- VISUALIZATION TUTORIAL
+   When running in multi-threading mode, the histograms accumulated on threads are
+   automatically merged in a single output file, while the ntuple is written
+   in files per thread.
+  
+  8- VISUALIZATION TUTORIAL
   
    Additional visualization tutorial macros are available in the visTutor
    subdirectory.  They can be tried as:
@@ -168,6 +188,38 @@ $Id$
    For details, see comment lines  described in the macro files.
    These macros are designed to help your understanding of the User's Guide.
    
+ 9- HOW TO RUN
+ 
+    This example handles the program arguments in a new way.
+    It can be run with the following optional arguments:
+    % exampleB4a [-m macro ] [-u UIsession] [-t nThreads]
+    
+    The -t option is available only in multi-threading mode
+    and it allows the user to override the Geant4 default number of 
+    threads. The number of threads can be also set via G4FORCENUMBEROFTHREADS
+    environment variable which has the top priority.
+ 
+    - Execute exampleB4a in the 'interactive mode' with visualization
+        % exampleB4a
+      and type in the commands from run1.mac line by line:  
+        Idle> /tracking/verbose 1 
+        Idle> /run/beamOn 1
+        Idle> ...
+        Idle> exit
+      or
+        Idle> /control/execute run1.mac
+        ....
+        Idle> exit
+
+    - Execute exampleB4a in the 'batch' mode from macro files
+      (without visualization)
+        % exampleB4a -m run2.mac
+        % exampleB4a -m exampleB4.in > exampleB4.out
+ 		
+    - Execute exampleB4a in the 'interactive mode' with a selected UI session,
+      e.g. tcsh
+        % exampleB4a -u tcsh 
+
  The following paragraphs are common to all basic examples
        				
  A- VISUALIZATION
@@ -214,33 +266,3 @@ $Id$
    The selection of the user command interface is then done automatically 
    according to the Geant4 configuration or it can be done explicitly via 
    the third argument of the G4UIExecutive constructor (see exampleB4a.cc). 
- 
- C- HOW TO RUN
- 
-    This example handles the program arguments in a new way.
-    It can be run with the following optional arguments:
-    % exampleB4a [-m macro ] [-u UIsession]
- 
-    - Execute exampleB4a in the 'interactive mode' with visualization
-        % exampleB4a
-      and type in the commands from run1.mac line by line:  
-        Idle> /tracking/verbose 1 
-        Idle> /run/beamOn 1
-        Idle> ...
-        Idle> exit
-      or
-        Idle> /control/execute run1.mac
-        ....
-        Idle> exit
-
-    - Execute exampleB4a in the 'batch' mode from macro files
-      (without visualization)
-        % exampleB4a -m run2.mac
-        % exampleB4a -m exampleB4.in > exampleB4.out
- 		
-    - Execute exampleB4a in the 'interactive mode' with a selected UI session,
-      e.g. tcsh
-        % exampleB4a -u tcsh 
-
- 
-