Import Geant4 10.0.0 source tree

examples/basic/B1/.README

@@ -1,4 +1,4 @@
-//$Id$
+//$Id: .README 78001 2013-12-02 08:24:53Z gcosmo $
 
 ///\file "B1/.README"
 ///\brief Example B1 README page
@@ -6,8 +6,8 @@
 /*! \page ExampleB1 Example B1
 
  This example demonstrates a very simple application where an energy
- deposit is accounted in user actions and a dose in a selected volume
- is calculated. 
+ deposit is accounted in user actions and their associated objects
+ and a dose in a selected volume is calculated. 
 
 \section B1_s1 GEOMETRY DEFINITION
 	
@@ -21,7 +21,8 @@
    The materials are created with the help of the G4NistManager class,
    which allows to build a material from the NIST database using their
    names. Available materials and their compositions can be found in 
-   <a href="http://geant4.web.cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/apas10.html">
+   <a href="http://geant4.web.cern.ch/geant4/UserDocumentation/UsersGuides
+                                    /ForApplicationDeveloper/html/apas10.html">
    the Geant4 User's Guide for Application Developers, Appendix 10: 
    Geant4 Materials Database
    </a>.
@@ -32,7 +33,8 @@
    in this example are set in the QBBC physics list. This physics list 
    requires data files for electromagnetic and hadronic processes.
    See more on installation of the datasets in
-   <a href="http://geant4.web.cern.ch/geant4/UserDocumentation/UsersGuides/InstallationGuide/html/ch03s03.html">
+   <a href="http://geant4.web.cern.ch/geant4/UserDocumentation/UsersGuides
+                                         /InstallationGuide/html/ch03s03.html">
    Geant4 Installation Guide, Chapter 3.3: Note On Geant4 Datasets </a>.
    The following datasets: G4LEDATA, G4LEVELGAMMADATA, G4NEUTRONXSDATA and 
    G4SAIDXSDATA are mandatory for this example.
@@ -42,8 +44,24 @@
 /process/(in)activate processName
 \endverbatim
      allows to activate/inactivate the processes one by one.
+     
+\section B1_s3 ACTION INITALIZATION
 
-\section B1_s3 PRIMARY GENERATOR
+   A newly introduced class, B1ActionInitialization, 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:
+      B1ActionInitialization::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
+      B1ActionInitialization::BuildForMaster() 
+   which is invoked only in multi-threading mode.
+     
+\section B1_s4 PRIMARY GENERATOR
 
    The primary generator is defined in the B1PrimaryGeneratorAction class.
    The default kinematics is a 6 MeV gamma, randomly distributed in front
@@ -51,17 +69,26 @@
    This default setting can be changed via the Geant4 built-in commands 
    of the G4ParticleGun class.
    
-\section B1_s4 DETECTOR RESPONSE
+\section B1_s5 DETECTOR RESPONSE
 
    This example demonstrates a simple scoring implemented directly
-   in the user action classes. Alternative ways of scoring via
-   Geant4 classes can be found in the other examples.   
+   in the user action classes and B1Run object. 
+   Alternative ways of scoring via Geant4 classes can be found in the 
+   other examples.
    
-   It is in B1SteppingAction that the energy deposition is collected 
-   for a selected volume step by step and the statistical event by event 
-   accumulation of energy deposition is done within B1EventAction. 
-   Information about the primary particle is printed in the
-   B1RunAction::EndOfRunAction() along with the computation of the dose. 
+   The energy deposited is collected step by step for a selected volume
+   in B1SteppingAction and accumulated event by event in B1EventAction.
+   
+   At end of event, the value acummulated in B1EventAction is added in B1Run
+   and summed over the whole run (see B1EventAction::EndOfevent()).
+   
+   Total dose deposited is computed at B1RunAction::EndOfRunAction(), 
+   and printed together with informations about the primary particle.
+   
+   In multi-threading mode the energy accumulated in B1Run objects per
+   workers is merged to the master in B1Run::Merge() and the final
+   result is printed on the screen.
+
    An example of creating and computing new units (e.g., dose) is also shown 
    in the class constructor.