----------------------------------------------------------------------------- GLEPS 1.25 Installation and Use M. L. McConnell UNH MAY-2007 R. M. Kippen LANL MAY-2007 ----------------------------------------------------------------------------- N.B. Version 1.22+ will only work with geant3.21/14+ N.B. Version 1.24 should be used in place of version 1.22 and 1.23. INTRODUCTION: ============= This document describes the installation and use of the GEANT Low-Energy Polarized Scattering (GLEPS) package. This package incorporates polarization effects into the coherent (Rayleigh) and incoherent (Compton) scattering routines provided in the standard GEANT3 software package. The GLEPS package incorporates the GEANT Low-Energy Compton Scattering (GLECS) package, developed by R. M. Kippen. GLECS itself provides more detailed physical models of the coherent (Rayleigh) and incoherent (Compton) photon scattering processes than those included in the standard GEANT distribution. GLEPS (like GLECS) can be used with practically any simulation program based on the GEANT3 (FORTRAN) system. GLEPS PHYSICS OVERVIEW: ======================= The angular distribution of scattered photons in both coherent (Rayleigh) and incoherent (Compton) scattering will generally depend on the plane of polarization of the incident photon. This dependence is not included in the standard GEANT3 distribution, nor is it included in the GLECS package (see below). In many cases, polarization effects can be ignored. In other cases, however, these effects can be quite important, especially if one is interested in modeling the polarization sensitivity of an experiment. GLEPS was designed to incorporate polarization effects for both coherent (Rayleigh) and incoherent (Compton) scattering. THESE EFFECTS ARE ONLY INCLUDED FOR THE PRIMARY PHOTON. The user specifies an initial polarization vector for each incident photon, which is then subsequently tracked during scatterings of the primary photon. The angular distribution of the scattered photon is based on the polarization vector of the photon at the point where it scatters. The resulkting polarization of the scattered photon is also determined. GLEPS is not designed to handle the polarization of secondary photons (e.g., K-shell flourescence photons or annihilation photons). This would require some specification of the intial polarization vector by the routines that generate the secondary photons, a capability that does not currently exist within GEANT3. [1] Matt, G., Feroci, M., Rapisarda, M., and Costa, E., "Treatment of Scattering of Linearly Polarized Photons in Monte Carlo Codes," Radiat. Phts. Chem., Vol. 48, No. 4, pp. 403-411 (1996). [2] Namito, Y., and Hirayama, H., "LSCAT: Low-Energy Photon-Scattering Expansion for the EGS4 Code (Inclusion of Electron Impact Ionization)," KEK Internal 2000-4, May, 2000. (Available on the web at 'http://ccwww.kek.jp/kek/rad/egs4/lowen.html'.) GLECS PHYSICS OVERVIEW: ======================= THE ORIGINAL GLECS DISTRIBUTION IS AVAILABLE ON THE WEB AT: http://nis-www.lanl.gov/~mkippen/actsim/glecs/ SEE ALSO THE GLECS README FILE INCLUDED WITH THIS DISTRIBUTION. In GEANT3, Compton scattering is modeled using the approximation of a photon scattering with an electron at rest. In reality, the electron is not at rest, but rather bound in an atomic system with some corresponding orbital momentum. Ignoring the bound electron momentum leads to errors in the angular/energy distribution of the scattered photons. These errors become important for scattering below a few hundred keV. The GLECS treatment of Compton scattering accounts for bound electron momentum on a shell-by-shell basis using evaluated data read from tables. The treatment is derived nearly verbatim from [1] and users should consult this reference for a full description. Briefly, the GLECS treatment differs from standard GEANT3 in the following ways: A) The probability of a Compton scatter is evaluated using the total Compton cross section. In GLECS, the total cross sections for an element are interpolated from the Evaluated Photon Data Library (EPDL [2]) tables. These data include electron binding effects and are valid from 10 ev to 100 GeV. For compound materials, a weighted average of the individual element cross-sections is used, based on the relative number of electrons for each element in the material. B) The scattered photon angle is sampled from the differential Compton cross-section. In GLECS, this is the free-electron Klein-Nishina formula multiplied by the incoherent scattering form factor interpolated from EPDL data. The EPDL form factor represents the combination of all electron shells from a particular element. For compound materials, a particular element is chosen at random based on the relative number of electrons for each element in the material. C) The "Doppler broadened" scattered photon energy is sampled based on the distribution of bound electron momentum. These distributions ("Compton profiles") for each atomic electron sub-shell are taken from Atomic Data tables (see [1,3]). The appropriate sub-shell is randomly sampled based on the electron occupancy and the shell ionization potential. The bound electron momentum is then sampled from the Compton profile. This allows the energies of the scattered photon and (by conservation of energy) scattered electron to be computed. The technique used for simulating Rayleigh (or coherent) scattering in standard GEANT3 suffers from two major problems. First, the tabulated scattering form factor is sampled incorrectly, resulting in completely incorrect scatter angles and energies. Second, the form factor tabulation was interpolated on the same grid as that of the total cross section, which is typically far too coarse to be useful. In GLECS2.0 these problems were fixed, but in doing so the functions used in GEANT to approximate the form factors were pushed below their range of validity, leading to incorrect results for some material elements. In GLECS3.0+ the approach to Rayleigh was completely changed and no longer relies on GEANT for data. The approach is now similar to that for Compton scattering: total Rayleigh cross section and form factor data are interpolated from the Evaluated Photon Data Library (EPDL) tables. For compound materials, a weighted average of the individual element cross-sections is used, based on the relative number of electrons for each element in the material. The scattered photon angle is sampled using the Thomson cross section multiplied by the incoherent scattering form factor interpolated from EPDL data. The EPDL Rayleigh form factor represents the combination of all electron shells from a particular element. For compound materials, a particular element is chosen at random based on the relative number of electrons for each element in the material. [1] Namito, Y., Ban, S., & Hirayama, H., "Implementation of the Doppler Broadening of a Compton-Scattered Photon Into the EGS4 Code," Nucl. Inst. Meth. in Phys. Res. A 349, 489-494 (1994). [2] D.E. Cullen, S.T. Perkins, and J.A. Rathkopf, "The 1989 Livermore Evaluated Photon Data Library (EPDL)," UCRL-ID-103424, Lawrence Livermore National Laboratory (1990). [3] Biggs, F., Mendelsohn, L. B., & Mann, J. B., "Hartree-Fock Compton Profiles for the Elements," At. Data Nucl. Data Tables 16, 201-309 (1975). REQUIREMENTS: ============= In principle, GLEPS can be used with any existing GEANT3.21X simulation program. This may not be the case, however, mainly because of changes in GEANT common block definitions from time to time. GLEPS1.22 is designed and tested with GEANT3.21/14. It will not work properly with earlier GEANT versions. GLEPS1.21 is compatible with earlier GEANT versions (tested as far back as GEANT 3.2110, 1994). Furthermore, GLEPS was mainly designed to be installed on computers running various flavors of the UNIX operating system (tested on SGI & Sun platforms). Users of other systems may be able to use the package after minor changes. GLEPS requires current (later than 1994) versions of the CERN program library archive (i.e., ".a") files for your computer (available via ftp://asisftp.cern.ch/) and the GNU utilities "gunzip" and "gmake" (available via cern or via http://www.gnu.org/). Note that GLEPS is a FORTRAN package and is therefore NOT compatible with GEANT4 (c++). INSTALLATION: ============= Unpacking: ---------- The GLEPS package is distributed via a unix archive "tar" file that has been compressed with the gzip utility. Unpacking the file will result in the creation of a directory structure below the current directory. The commands to unpack the distribution file are "gunzip .tar.gz" followed by "tar -xvf .tar", where is the base name of the GLEPS distribution file. Files & Directories: -------------------- Successful unpacking of the GLEPS distribution file will result in the following files and directory structure beneath the current directory. gleps/ == main GLEPS package directory GNUmakefile --GNU makefile to compile the gleps programs README_GLEPS_v1.22 --This file README_GLECS_v3.34 --The original GLECS README file gleps.f --Source code for the GLEPS examp.f --Example application program using GLEPS include/ == Include files used by GLEPS data/ == Data tables accessed at run-time by all GLEPS programs Compilation: ------------- Before building GLEPS, make sure the environment variable CERN_ROOT points at your latest cernlib distribution directory (e.g., /usr/local/lib/cernlib/97a) and that the up-to-date archive libraries (i.e., ".a" files) exist in $CERN_ROOT/lib. To build GLEPS, type "gmake" from the gleps directory. This compiles the FORTRAN code and links it to the various CERN program libraries (including GEANT3), resulting in an object file named "gleps.o" and an executable program called "examp". The executable is an example program that illustrates how to use GLEPS. USING GLEPS: ============ At run time the GLEPS package requires that an environment variable called GLECS_DATA point to the location of the GLECS data files (e.g., gleps/data). [Note that we have retained the GLECS prefix for these data, since they remain unchanged from the GLECS distribution. But they are located in the gleps/data subdirectory.] You should set this variable in your login script if you plan to use GLEPS with other programs regularly. GLEPS operates by completely replacing the default GEANT3 Compton and Rayleigh processes. An example of its use is given in the "examp" program. All of the GLEPS physics handling is contained in the gleps.o compiled object file. To use GLEPS for Compton and Rayleigh scattering, rather than the standard GEANT3, simply include gleps.o in the link list prior to the GEANT library. For example, as illustrated in the GNUmakefile, use: f77 gleps.o -L$(CERNLIB) -lgeant -lpacklib where represents the file(s) containing source code for your GEANT application program. On most compilers, this will force the GLEPS routines to be used rather than any others with the same name that occur later in the link list. If your compiler complains and fails, there is probably a switch to force the desired behavior. Within the GEANT application, everything behaves in the usual manner. However, the user is given enhanced control over the Compton and Rayleigh processes via the ICOMP and IRAYL physics flags, which behave as follows: ICOMP = 0 No Compton scattering. ICOMP = 1 (GEANT3 DEFAULT) Compton scattering WITH generation of e- in the same manner as standard GEANT3. ICOMP = 2 Compton scattering WITHOUT generation of e- in the same manner as standard GEANT3. The scattered electron's energy is directly deposited in the current medium. ICOMP = 3 Compton scattering WITH generation of e- including Doppler broadening and using EPDL cross sections and scattering form factors. If the photon is the primary photon (ISTAK=0), then polarization effects are included. ICOMP = 4 Compton scattering WITHOUT generation of e- including Doppler broadening and using EPDL cross sections and scattering form factors. The scattered electron's energy is directly deposited in the current medium. If the photon is the primary photon (ISTAK=0), then polarization effects are included. IRAYL = 0 (GEANT3 DEFAULT) No Rayleigh scattering. IRAYL = 1 Rayleigh scattering in the same manner as standard GEANT3. (do not use since it is completely wrong!) IRAYL = 2 Rayleigh scattering using EPDL cross sections and scattering form factors. If the photon is the primary photon (ISTAK=0), then polarization effects are included. Note that the ICOMP and IRAYL flags can be set globally via the GEANT common block (or through the use of FFREAD data keys), or locally (for a particular tracking medium) via calls to the GSTPAR(NUMED,'ICOMP',IVAL) routine. GLEPS makes use of the GEANT3 COMMON block GCTPOL, whose original purpose was to track the polarization of Cerenkov photons. Here we use this COMMON block solely for the purpose of tracking the polarization of the primary photon. In this regard, the user must ensure that the polarization vector (POLAR) is specified for each incident photon. Furthermore, this vector must be defined to be perpendicular to the direction of propagation of the photon. (Currently, GLEPS does not provide a check to insure that this condition is met.) Finally, it should be noted that the definition of the overall simulation energy range, cross section binning, and particle energy cuts in GEANT should be defined explicitly in the user program (see examp.f). The GEANT default is 100 log-spaced bins from 10 keV to 10 TeV with typical gamma/electron cuts of 10 keV. This is rather sparse for accurate low-energy simulations. Furthermore, the data used by GLECS are valid to lower energies than usually employed in GEANT, it is thus possible to extend the valid range below the typical 10 keV cut. In principle, the minimum energy could be set to 10 ev. However, be aware that the standard GEANT3 physics is still used for the photoelectric effect. These cross sections may have large errors below ~1 keV. EXAMPLE PROGRAM: =============== The examp program provides a simple demonstration of GLEPS. It is a stand-alone program (apart from the GLECS data files) where all the control parameters are "hard coded". Photons with energy 40 keV are normally incident on a small silicon disc (1 mm thick, 1 cm diameter). A ring of NaI 2 cm thick x 2 cm high surrounds the disk at a radius of 50 cm. Photons must therefore scatter at an angle near 90 deg to be detected in the NaI. Cumulative energy deposits in the Si and NaI are recorded (and printed to the user terminal) for 10 events, where an event is any photon that deposits energy in the NaI. A sample portion of the output is given below. .--------------------------------------------------. | EXAMP -- GLEPS EXAMPLE PROGRAM | '--------------------------------------------------' NEVENT = 10 PARTYP = 1 PARENE = 40.000000 keV ICOMP = 3 IRAYL = 2 Generating 10 events. ========================================================================================== Iev Nin NH1 NH2 E_Si E_NaI E_Tot ANG X Y Z ========================================================================================== 1 11534 2 2 2.85 8.54 11.39 128.48 1 0.10 0.00 0.00 0.00 2 2.75 0.00 0.00 0.00 1 4.56 -31.00 39.00 0.00 2 3.98 -31.00 39.00 0.00 ------------------------------------------------------------------------------------------ 2 106493 1 3 2.89 37.10 39.99 15.15 1 2.89 0.00 0.00 0.00 1 0.87 48.00 13.00 0.00 2 32.29 48.00 13.00 0.00 3 3.94 48.00 13.00 0.00 ------------------------------------------------------------------------------------------ 3 124080 2 3 3.10 36.90 40.00 139.03 1 0.10 0.00 0.00 0.00 2 3.00 0.00 0.00 0.00 1 0.93 -38.00 33.00 0.00 2 32.24 -38.00 33.00 0.00 3 3.73 -38.00 33.00 0.00 ------------------------------------------------------------------------------------------ 4 138689 1 2 2.60 9.08 11.68 126.87 1 2.60 0.00 0.00 0.00 1 4.85 -30.00 40.00 0.00 2 4.23 -30.00 40.00 0.00 ------------------------------------------------------------------------------------------ 5 147971 0 3 0.00 40.00 40.00 173.16 1 4.85 -50.00 6.00 0.00 2 28.32 -50.00 6.00 0.00 3 6.83 -50.00 6.00 0.00 ------------------------------------------------------------------------------------------ 6 178517 0 3 0.00 40.00 40.00 255.96 1 4.56 -12.00 -48.00 0.00 2 28.61 -12.00 -48.00 0.00 3 6.83 -12.00 -48.00 0.00 ------------------------------------------------------------------------------------------ 7 183180 0 3 0.00 40.00 40.00 107.35 1 1.25 -15.00 48.00 0.00 2 3.31 -15.00 48.00 0.00 3 35.44 -15.00 48.00 0.00 ------------------------------------------------------------------------------------------ 8 203605 2 2 2.93 8.46 11.39 314.19 1 1.84 0.00 0.00 0.00 2 1.09 0.00 0.00 0.00 1 4.56 35.00 -36.00 0.00 2 3.90 35.00 -36.00 0.00 ------------------------------------------------------------------------------------------ 9 217723 1 2 2.79 8.89 11.68 115.02 1 2.79 0.00 0.00 0.00 1 4.85 -21.00 45.00 0.00 2 4.04 -21.00 45.00 0.00 ------------------------------------------------------------------------------------------ 10 223787 0 3 0.00 40.00 40.00 298.61 1 4.56 24.00 -44.00 0.00 2 28.61 24.00 -44.00 0.00 3 6.83 24.00 -44.00 0.00 ------------------------------------------------------------------------------------------ 1 **** NUMBER OF EVENTS PROCESSED = 10 **** RANDOM NUMBER GENERATOR AFTER LAST COMPLETE EVENT 1601513962 1493067425 **** TIME TO PROCESS ONE EVENT IS = 29.2000 SECONDS For each event, the first line in the output file contains the following : Iev - The event number Nin - The number of input photons NH1 - The number of "hits" in the Si detector NH2 - The number of "hits" in the NaI detector E_Si - The total energy deposited in the Si (keV, summed over all "hits") E_NaI - The total energy deposited in the NaI (keV, summed over all "hits") E_tot - The total energy deposited (keV, sum of E_Si and E_NaI) ANG - The azimuthal scatter angle (degrees) The subsequent lines for each event output contains NH1 lines giving the energy deposit and location (X,Y,Z, in cm) for each "hit" in the Si detector, followed by NH2 lines giving the energy deposit and location (X,Y,Z, in cm) for each "hit" in the NaI detector. In addition, the examp program creates a text data file ('examp.dat') that contains one line per event, giving the following: Iev - The event number Nin - The number of input photons E_Si - The total energy deposited in the Si (keV, summed over all "hits") E_NaI - The total energy deposited in the NaI (keV, summed over all "hits") E_tot - The total energy deposited (keV, sum of E_Si and E_NaI) ANG - The azimuthal scatter angle (degrees) You can then try re-running the program with ICOMP=1 by editing the examp.f file and recompiling. You should note that more events are clustered near the Compton edge of ~37 keV when Doppler broadening is turned off. Enterprising users should simulate more events and histogram the results to see the detailed effects of Doppler broadening and Rayleigh scattering. For the purposes of experimentation, the following parameters will be of most interest: In the main routine (EXAMP)... NEVENT - The number of events to generate EPART - The incident photon energy (GeV) ICOMP - Compton control flag IRAYL - Rayleigh control flag In subroutine GUKINE... POLAR(1) - X-component of polarization (unit) vector POLAR(2) - Y-component of polarization (unit) vector POLAR(3) - Z-component of polarization (unit) vector (= 0 for photon propagating along z-axis) DOCUMENT HISTORY: ================= 1.25/MAY-2007....Bug fix: package is now compatible with the use of energy loss straggling (ISTRA > 0). Thanks to bug report from Alessio Mangiarotti. Updated README file. 1.24/MAY-2004....Bug fix in routine GTGAMA - since version 1.22 the GLEPS scattering routines were not being called. This is now fixed. 1.23/MAY-2004....Incorporate changes from GLECS3.35 See GLECS readme file for details. 1.22/DEC-2003....Incorporate changes from GLECS3.34 to make compatible with GEANT3.21/14 See GLECS readme file for details. 1.21/MAY-2003....Bug fix in gtgama that caused incorrect results on some compilers. Also bug fixes for use with g77. GLEPS v1.2.1 1.20/MAY-2003....First version. GLEPS v1.2.0 GLEPS-RELATED PROBLEMS/QUESTIONS: ================================= e-mail: mark.mcconnell@unh.edu phone: 603-862-2047 FAX: 603-862-3584 mail: Dr. Mark McConnell University of New Hampshire Space Science Center Morse Hall Durham, NH 03824 GLECS-RELATED PROBLEMS/QUESTIONS: ================================= e-mail: mkippen@lanl.gov phone: 505-667-3125 FAX: 505-667-4414 mail: Dr. R. Marc Kippen ISR-1, Space and Remote Sensing Sciences Mail Stop B244 Los Alamos National Laboratory Los Alamos, NM 87545 Users are encouraged to acknowledge the authors in any publications or presentations that include results using GLECS/GLEPS. -------------------------------------------------------------------------------- -eof-