#--------------------------------------------------------
#   "kammc"
#  
#   KamLAND Monte Carlo developed 9/99 by LH
#   
#    12/99 BT-  Minor cleanup and distribution preparation          
#
#   Some documentation for this code follows:
#---------------------------------------------------------
    
-----------SOURCE NOTES------------------------------------
    The source files in this directory may be divided into:
    README                  -- this description.
    configure, Makefile.in  -- for compilation
    user/*.f                -- user modifiable calculation and run
			        files
    geometry/*.f            -- The KamLAND GEANT geometry source
    radsrc/*.f              -- generator code for radiation in the
			        geometry
    elements/*.f            -- Generator of U/TH/K/Co/Rn decays
    scripts/*.sh 
    scripts/*.kumac         -- useful scripts for running the code
    include/*.inc           -- Include files for the Fortran
    geantinc/*.inc          -- (CMZ undone include files for GEANT)


      Of particular interest inside the user subdirectory are

    kam_dtktr_uhist.f       -- Code to book histograms for analysis
    kam_dtktr_geom.f        -- The KamLAND geometry control
    kam_dtktr_gukine.f      -- Code to control single event generation.
    kam_dtktr_uglast.f      -- Analysis code at end of program execution.

-----------ENVIRONMENT VARIABLES----------------------------------

 The compilation script "configure" assume various environment variables are
defined to tell the script where everything is.  IF these variables
are not assigned, the script will look in various standard locations
for the relevant libraries.


    $X11_ROOT   where the X11 libraries reside.  
    $CERN_ROOT  where the cern libraries reside, e.g. /usr/local/cern/2000
    $GEANT321_ROOT  where geant sits, if not in the cern distribution
                  e.g. $CERN_ROOT
    $ROOTSYS  where ROOT sits ( this program doesn't need ROOT,
                this is just an artifact of using the same configure
		for everything).
    
-----------DIRECTORY STRUCTURE------------------------------

  The Makefile in this directory will create and executable
"kammc".  It will be copied to the directory ../bin.  It is assumed that
../bin is in your $PATH.

-----------COMPILATION-------------------------------------
To compile the source here try,

     configure; make
    OR
     configure debug; make.     ! to debug the mc
    OR    
     configure profile; make    ! to profile the mc

Compilation has only been tested on Linux/RH[56] so far.
Linking the source requires a valid fortran 77 compiler and distribution, as
well as precompiled cern libraries, in the other
directories.
   Upon successful compilation, the executable will be

    ./kammc            


-----------REQUIRED INPUTS TO RUN---------------------------

1.  INPUT:  This file contains input cards(configuration commands)
    used by GEANT3 and the KamLAND source.  Examples include
    defining the material and decay types for simulating 
    background radioactivity in KamLAND.

2.  pmtpos.txt:  This file has a map of the locations of the PMTs
    on  the KamLAND steel sphere.

3.  INPUT1:  This file simply contains the name of the histogram
     output file  from the MC.

-----------RUNNING: THE SIMPLE WAY--------------------------

    ./kammc            
 for batch operation.  Or try
   
    ./kammc -i
for the interactive version.  3/31--not yet functional, BT.