$Id: README,v 1.9 2002/06/18 23:46:12 pia Exp $
-------------------------------------------------------------------

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

                            xray_telescope
                            --------------
XrayTel is an advanced Geant4 example based on a realistic simulation of 
an X-ray Telescope.  It is based on work carried out by a team of Geant4 
experts to simulate the interaction between X-ray Telescopes XMM-Newton 
and Chandra with low energy protons present in the orbital radiation 
background.  The X-ray mirrors are designed to collect x-ray photons at
grazing-incidence angles and focus them onto detectors at the focal plane.
However, this mechanism also seems to work for low energy protons which,
if they reach the detectors in sufficient numbers, can cause damage.
In this example, the geometry has been simplified by using a single mirror 
shell and no baffles, but all the dimensions and materials are realistic.

The aim of this advanced example is to illustrate the use advanced 
GUI, visualisation, particle generation and analysis schemes available 
in Geant4:

 - the simulation can be run from GAG or the command prompt

 - macros are provided to display the geometry and particle tracks with 
   OpenGL, DAWN Postscript or VRML visualisation

 - the generation of particles is done via the new General Particle Source

 - histograming facilities are available through the AIDA interfaces.
   The implementation shown in this example is obsolete, and will be
   updated in a future release; for an up-to-date illustration of how to
   embed an AIDA-compliant analysis in a Geant4-based simulation
   application, please see the other advanced examples in this
   Geant4 release (brachytherapy, gammaray_telescope, underground_physics,
   xray_fluorescence).

In order to be able to use any of these packages, prior installation is 
necessary and a number of environment variables will have to be set.


1. Setting up the environment variables for GAG, Visualisation and 
   Analysis options (example based on Linux at CERN)

#set up GAG 
setenv G4UI_BUILD_GAG_SESSION       1
setenv G4UI_USE_GAG                 1

#set up VRMLview
setenv G4VIS_BUILD_VRMLFILE_DRIVER  1
setenv G4VIS_USE_VRML               1
setenv G4VIS_USE_VRMLFILE           1
setenv G4VRMLFILE_MAX_FILE_NUM     100
setenv G4VRMLFILE_VIEWER        vrmlview    #if installed
setenv G4VIS_USE_VRML               1
setenv G4VIS_USE_VRMLFILE           1
setenv PATH ${PATH}:"/afs/cern.ch/sw/contrib/VRML/bin/Linux"

#set up OpenGL or Mesa 
setenv G4VIS_BUILD_OPENGLX_DRIVER   1
setenv G4VIS_USE_OPENGLX            1
setenv OGLHOME /afs/cern.ch/sw/geant4/dev/Mesa/Linux-g++

#set up DAWN
setenv G4VIS_BUILD_DAWN_DRIVER      1
setenv G4VIS_BUILD_DAWNFILE_DRIVER  1  
setenv G4VIS_USE_DAWN               1
setenv G4VIS_USE_DAWNFILE           1
setenv PATH ${PATH}:"/afs/cern.ch/sw/geant4/dev/DAWN/Linux-g++"

# flag that we want to use analysis:
setenv G4ANALYSIS_USE               1

# select analysis system: any AIDA 2.2 compliant system or Anaphe 3.6.5

# set up for AIDA 2.2 compliancy:
# Compilation and link flags to hook and AIDA compliant system 
# are passed to the Geant4 GNUmakefile system by using the "aida-config" tool
# that should come with any AIDA compliant system. Examples are:
# setenv G4ANALYSIS_AIDA_CONFIG_CFLAGS `aida-config --include`
# setenv G4ANALYSIS_AIDA_CONFIG_LIBS   `aida-config --libs`

#set up Anaphe/Lizard for the gcc-2.95 compiler
setenv G4ANALYSIS_SYSTEM Lizard
setenv G4ANALYSIS_USE_LIZARD        1
setenv G4ANALYSIS_BUILD             1
setenv G4ANALYSIS_BUILD_LIZARD      1
setenv PATH ${PATH}:/afs/cern.ch/sw/lhcxx/specific/redhat61/gcc-2.95.2/3.6.5/bin
source /afs/cern.ch/sw/lhcxx/share/LHCXX/3.6.5/install/sharedstart.csh

#add to the LD_LIBRARY_PATH 
setenv LD_LIBRARY_PATH $OGLHOME/lib


IMPORTANT WARNING! 
setenv G4ANALYSIS_BUILD  1 
must always be set to build the example even if the analysis option 
is not required 


Sources
-------

GAG can be obtained from

http://erpc1.naruto-u.ac.jp/~geant4/

OpenGL Mesa needs to be installed prior to building Geant4 and can be
downloaded from

http://www.mesa3d.org/download.html

DAWN can be obtained from

http://133.7.51.8/dawn/

VRMLview for Linux can be obtained from



2. Run
To execute a sample simulation with visualisation of proton tracks
reaching the detector run:

XrayTel 

execute command "/control/execute xxxxx.mac"

visualisation macros provided are 
  - opengl.mac  for OpenGL display
  - vrml.mac    for VRML display and output file
  - dawn.mac    for dawn display and PS output file

To execute a run without visualisation use 
  - test.mac


If the analysis options are set, histograming windows will
automatically open and the corresponding files will be created.
A 2D histogram (scatter plot) will display in real time every proton 
hit that reaches the detector. 
A 1D histogram will display the energy distribution of the protons
that reach the detector at the end of the run.

The final energy and (x,y,z) position of the protons that reach the 
detector is output to a file "detector.hits".  This file is created
if it does not exist or appended to if it does. 


3. Detector description

The telescope and detector geometry is defined in 
XrayTelDetectorConstruction.cc

4. Physics processes

The physics processes are in XrayTelPhysicsList.cc
The main process in this example is MultipleScattering of the protons
on the mirror surfaces.

5. Event generation

This is done using the new General Particle Source. Documentation for 
this can be found in

http://www.space.dera.gov.uk/space_env/gspm.html

6. Analysis

At present there are two options for analysis packages: either 
explicitely the Anaphe 3.6.5 (or compatible) version is selected, 
or any AIDA-2.2 compliant analysis system is chosen.  This dual
approach will be removed in the next release when only the AIDA
compliant version will be present. Presently, the OpenScientist 
package (version 8) provides an implementation of AIDA 2.2, 
other packages as Anaphe and JAS will follow soon. The AIDA 
compliant version has not been tested by the developers and is
here as a example of "forward compatibility" on how to use analysis.

To build and execute the example on platforms where there is no
implementation of the analysis system, the environment variables 
must not be set, except for G4ANALYSIS_BUILD which is required for 
building the executable.












