source: trunk/examples/advanced/underground_physics/README @ 1321

------------------------------Advanced Example---------------------------------                                 README FILE


NB: The documentation for this example is in the process of being updated.
Please go to http://www.ge.infn.it/geant4/examples/ for the most up-to-date
description, manual, design documentation and users requirement/traceability.

JUNE 2002:
The underground physics example has been updated since the December Geant4.0
release to include:  1) Analysis, using AIDA 2.2 and tested against Anaphe 4.0
                     2) Full lab geometry - important for neutron scattering
                     3) Updated macros/messengers
                     4) Correction of a few minor features

The messengers can be seen from typing help within the UI.
Additional file handling and time/energy cut messengers have been implemented.

(1) and (2) are discussed more fully below

Note: Due to the importation of data files during the initialisation stage of
Geant4, load-time may be in excess of 5 minutes.

UNDERGROUND PHYSICS

An example of a underground dark matter experiment.

Please see the UserRequirements.txt and related web-pages referred to
at the end of that document.

Over-view:
A single liquid xenon cell is simulated within Geant4 and the scintillation
light produced from interactions from various calibration species is recorded
as PhotoMultiplier hits.  The output is then written to an ASCII file for
future off-line analysis.

Geometry:
Experimental set-up:

  G4double worldWidth  = 470.0*cm + 2.*wallThick; // "x"
  G4double worldLength = 690.0*cm + 2.*wallThick; // "y"
  G4double worldHeight = 280.0*cm + 2.*wallThick; // "z"



A "cavern" of dimensions 5.18m x 7.38m x 3.28m with concrete walls is defined
as the World Volume.  A laboratory geometry is incorporated included desks,
cupboards, door and windows.  For ease this is included in a separate ".icc"
file which can be removed should the code seem cumbersome.  In the centre of 
the cavern a steel vacuum vessel containing liquid and gaseous xenon is placed.
The internal construction of the vessel accurately reproduces an existing 
prototype Dark Matter detector which allows experimental comparison. The active
detector volume is defined by a series of metal rings, complemented by
a cover mirror and a PMT immersed in the liquid.  Two grids and a
thermalising copper shield are also incorporated. The liquid/gas
interface is located 6mm away from the mirror surface. A Am241
calibration source is suspended from one of the grids in the liquid
phase, above the PMT.

      XXX================XXX mirror
      XXX________________XXX gas phase
      XXX                XXX 
      XXX                XXX liquid phase
      XXX                XXX
      XXX.......U........XXX grid + calibrator
      XXX................XXX grid
      XXX|              |XXX
         | ___------___ | 
         ||    PMT     ||
         ||            ||


Hits Output (file "hits.out"):
An ASCII file containing the following information:
     Evt #         : event number
     Etot, MeV     : energy deposited in liquid xenon
     LXe hits      : number of hits in liquid xenon
     LXeTime, ns   : time of first hit in liquid xenon
     PMT hits      : number of hits in PMT (photocathode)
     PmtTime, ns   : average PMT hit time relative to LXeTime
     First hit     : first particle to hit liquid xenon
     Flags         : particles contributing to energy deposition
     Seeds         : the initial seed values for given hit events

     Note:

     The time information PmtTime is erroneous when forcing nuclear
     decay with the RadioactiveDecay module due to the precision
     required to detect nanosecond scintillation times on a global
     time of 432 years (in the case of 241Am decay).


Pmt Output (file "pmt.out"):
Photon hit positions within the PMT face (overwritten every event):
"Hit#    X, mm   Y, mm   Z, mm"


To Run:
Either run the macro files interactively or in batch with the command
DMX macro_name.mac.


Macros:

   initInter.mac
   Initialisation macro for interactive mode.

   gamma.mac
   Shoots one 60 keV gamma upwards from the calibrator and traces the
   scintillation light produced in LXe to the PMT. All tracks are drawn
   with custom colours. PMT hits in photocathode are also shown. Event
   summary is writen to file "hits.out".

   gamma_1000.mac 
   Similar to above, but 1000 gammas are emmited isotropically from the
   source. No hits or tracks are draw, and the verbosity is reduced.

   alpha.mac
   Shoots one 5.486 MeV alpha particle upwards from the calibrator and
   traces the scintillation light to the PMT. All tracks except
   optical photons are drawn. Event summary is written to file
   "hits.out" and PMT hits to file "pmt.out".

   alpha_1000.mac
   Similar to above, but 1000 alphas are emmited isotropically from the
   source. No tracks are stored, and the verbosity is reduced. Event
   summary is written to file "hits.out", PMT hits are not written out.

   neutron.mac
   Shoots one 2.48 MeV neutron inside the room aimed at the detector. 
   All tracks except scintillation photons are drawn (custom colours).
   Gammas are not killed at the concrete wall. Event summery is written
   to file "hits.out".

   ambe_spectrum.mac
   Produces a spectrum of neutrons according to an approximation of a Am/Be
   neutron source.  However, this uses the GPS and therefore will only work
   after compilation with the DMXENV_GPS_USE environment variable (see below)


   sourceAm241.mac
   Forces the decay of 241Am nuclei in the calibrator and tracks the
   resulting particles (237Np + alpha + gamma from 237Np
   de-excitation). All tracks are drawn except scintillation photons.
   Event summery is written to file "hits.out".   
   -> To be added for a future release


   sourceAm241_1000.mac
   Similar to above but for 1000 events. No tracks are stored.
   -> To be added for a future release


Note: 
The following environment variables need to be set:
G4RADIOACTIVEDATA      : points to Radioactive Decay Data files
G4LEDATA               : points to low energy data base
G4LEVELGAMMADATA       : points to PhotoEvaporation data
NeutronHPCrossSections : points to neutron data files

In addition if you require to use the full General Particle Source then the
variable DMXENV_GPS_USE can be set.  The DMX gun is still included in order to
allow forward compatibility should the GPS change.


ANALYSIS:

In order to use the AIDA 3.2.1 compliant analysis set the environment variable
G4ANALYSIS_USE before building.  If a previous build exists a gmake clean has
to be executed.  

setenv G4ANALYSIS_USE 1

then gmake

The program should then produce hbook histogram files 

Using AIDA 3.2.1 interfaces three different analysis packages can be utilised:
Java Analysis Studio (JAS)
OpenScientist
PI

Please for more information look at http://aida.freehep.org 

SEEDS:

The seeds of event hits are stored in the hit record file.  These can be used
to repeat events for visualisation, test crashes/idiosyncracies:

/random/setDirectoryName ./seeds
/random/resetEngineFrom currentEvent.rndm
/random/saveThisEvent
/random/setSavingFlag

The file currentEvent.rndm should contain the two seeds which were outputed in
the scintHit file.

ERRORS:

When running interactively the following error will be shown:

BooleanProcessor::caseIE : unimplemented case
BooleanProcessor::caseIE : unimplemented case
BooleanProcessor::caseIE : unimplemented case
BooleanProcessor::caseIE : unimplemented case
BooleanProcessor::caseIE : unimplemented case
BooleanProcessor::caseIE : unimplemented case
BooleanProcessor: boolean operation failed
BooleanProcessor::caseIE : unimplemented case
BooleanProcessor::caseIE : unimplemented case
BooleanProcessor::caseIE : unimplemented case
BooleanProcessor::caseIE : unimplemented case
BooleanProcessor: boolean operation failed

This is a "feature" of the visualisation of boolean volumes, but does not
affect functionality/performance so can be ignored.

NB:
If using explicit libraries (?) i.e. non-shared then compilation time with
neutrons in physics list is very long (>5 minutes) - check this.............
It is more efficient to use shared libraries that are loaded at run-time with
increased initialisation time (at run-time).

Also if using shared libraries the load time at run-time may be several minutes
- this is partially due to the neutron implementation requires full data sets
for each isotope being specified.


--------------------------------------

If running on Redhat 7.0 or above set G4SYSTEM to Linux-g++, alternatively you
can install backward compatibility to egcs, however, requires
config/sys/Linux-egcs.gmk to be altered so that CXX is set to kgcc 
(compared to g++ in original file)

--------------------------------------


Alex Howard, 29/11/01
updated 18/06/02