
    =========================================================
    Geant4 - an Object-Oriented Toolkit for Simulation in HEP
    =========================================================

                       Extended Example for G4GeneralParticleSource (GPS)
                       --------------------------------------- 

  exgps is created to demonstrate the usage of G4GeneralParticleSource for generating 
  primary incident particle according to user defined distributions. These range from simple 
  monocromatic point source to complicated mutiple sources with various biasing schemes. 
  
  More detailed information on the usage of GPS are available on its home site: 
	http://reat.space.qinetiq.com/gps

  -------------------------------------------------------------------------------------------
  1. GEOMETRY

     Simple geometry consists of a "Vacuum" world and, in it with two other components:	     
 
       - An alunimium box : 20 x 20 x 20 cm in size, cerntered at the origin.
		  
       - A SiO2 sphere: 5 cm in radius and is placed in the centre of the aluminium box. 

  2. PHYSICS

	Tranportation process only for all particles.

  3. EVENT:

     The event generator is the G4GeneralParticleSource (GPS). The instantiation of G4GeneralParticleSource
     is same as that for G4ParticleGun. See the exGPSPrimaryGeneratorAction.cc file for details .  
  
  5. VISUALIZATION:
 
     Visualisation of the geometry and the tracks is possible with many of the G4 visualisation packages. An
     example of displaying the geometry and tracks using VRML is given in the macro file vis.mac.  

  6. ANALYSIS:

     This example implements an analysis manager which creates histograms and ntuples
     using Geant4 analysis tools.

     At the end of an excution, an xml file "exGPS.root" is created by default which contains 
     histograms and ntuples. 
     
     The output file contains 6 histograms and one ntuple:

	histogram 1: The energy spectrum of the primary particles.
	histogram 2: 2d histogram of primary particle incident position distribution in the X-Y plane.
	histogram 3: 2d histogram of primary particle incident position distribution in the X-Z plane.
	histogram 4: 2d histogram of primary particle incident position distribution in the Y-Z plane.
	histogram 5: 2d histogram of primary particle incident angle distribution in terms of Phi/Cos(Theta).
	histogram 6: 2d histogram of primary particle incident angle distribution in terms of Phi/Theta.

     The binnings of the histograms can be changed with the UI commands avialable under the 
     /analysis directory.
 
     In the ntuple the following data are recorded for each incident particle:  

	Particle ID
	Incident Position (x,y,z);
	Incident Angle (theta,phi);
	Particle weight;

  7. GETTING STARTED:

     Run the executable: 

     while in the exgps build directory do 

         exgps exrgps.in

 8. FURTHER EXAMPLES of MACRO FILES:

    There are a number of g4mac files in the ./macros subdirectory, to show the various features of GPS. 
    Most of them will lead to the creation of a Root file in the same name as the macro file. 
    These files can be then examined and analysed with ROOT.

	Please see the README file there for further information.



