-------------------------------------------------------------------------------- GLECS 3.36 Installation and Use R. M. Kippen LANL MAY-2007 -------------------------------------------------------------------------------- N.B. Version 3.34+ will only work with geant3.21/14+ N.B. Version 3.30+ will only work with version 3.30+ data files! INTRODUCTION: ============= This document describes the installation and use of the GEANT Low-Energy Compton Scattering (GLECS) package, which provides more detailed physical models of the coherent (Rayleigh) and incoherent (Compton) photon scattering processes than those included in the standard GEANT distribution. GLECS can be used with practically any simulation program based on the GEANT3 (FORTRAN) system. PHYSICS OVERVIEW: ================= 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, GLECS 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. GLECS3.3.4 is designed and tested with GEANT3.21/14. It will not work properly with earlier GEANT versions. GLECS3.3.3 is compatible with earlier GEANT versions (tested as far back as GEANT 3.2110, 1994). Furthermore, GLECS 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. GLECS 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 GLECS is a FORTRAN package and is therefore NOT compatible with GEANT4 (c++). INSTALLATION: ============= Unpacking: ---------- The GLECS 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 GLECS distribution file. Files & Directories: -------------------- Successful unpacking of the GLECS distribution file will result in the following files and directory structure beneath the current directory. glecs/ == main GLECS package directory GNUmakefile --GNU makefile to compile the glecs programs README --This file glecs.f --Source code for the GLECS examp.f --Example application program using GLECS include/ == Include files used by GLECS data/ == Data tables accessed at run-time by all GLECS programs Compilation: ------------- Before building GLECS, 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 GLECS, type "gmake" from the glecs directory. This compiles the FORTRAN code and links it to the various CERN program libraries (including GEANT3), resulting in an object file named "glecs.o" and an executable program called "examp". The executable is an example program that illustrates how to use GLECS. USING GLECS: ============ At run time the GLECS package requires that an environment variable called GLECS_DATA point to the location of the GLECS data files (e.g., glecs/data). You should set this variable in your login script if you plan to use GLECS with other programs regularly. GLECS 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 GLECS physics handling is contained in the glecs.o compiled object file. To use GLECS for Compton and Rayleigh scattering, rather than the standard GEANT3, simply include glecs.o in the link list prior to the GEANT library. For example, as illustrated in the GNUmakefile, use: f77 glecs.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 GLECS 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 (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. 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. IRAYL = 0 (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. 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. 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 GLECS. 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 -- GLECS EXAMPLE PROGRAM | '------------------------------------------------' NEVENT = 10 PARTYP = 1 PARENE = 40.00000 keV Generating 10 events. ICOMP = 3 IRAYL = 2 ============================================= Iev E_Si E_NaI E_Tot (keV) ============================================= 1 3.02 36.99 40.00 2 3.00 37.00 40.00 3 4.55 6.84 11.39 4 2.75 37.25 40.00 5 2.24 37.75 39.99 6 4.34 35.66 40.00 7 2.90 37.11 40.00 8 2.96 37.04 40.00 9 3.52 8.17 11.69 10 2.99 8.40 11.39 **** NUMBER OF EVENTS PROCESSED = 10 **** RANDOM NUMBER GENERATOR AFTER LAST COMPLETE EVENT 1406382862 339187943 **** TIME TO PROCESS ONE EVENT IS = 3.2720 SECONDS 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. DOCUMENT HISTORY: ================= 3.36/MAY-2007...Bug fix: package is now compatible with the use of energy loss straggling (ISTRA > 0). Thanks to bug report from Alessio Mangiarotti. 3.35/MAY-2004...Increased allowed length of GLECS_DATA to 256 chars. 3.34/DEC-2003...Change GEANT common GCKING for compatibility with GEANT version 3.21/14. Code is now incompatible with earlier versions of GEANT. Upgraded GTGAMA and GPHYSI for GEANT3.21/14. 3.33/AUG-2002...Bug fix that allows use of GLECS Rayleigh (IRAYL = 2) without GLECS Compton (ICOMP <= 2). 3.32/AUG-2002...Minor bug fix that allows compilation on Sun F77 compilers. 3.31/JUL-2002...Corrected bug in v3.30 that prevented Doppler broadening at large energies and large scatter angles. Also, ionization energy is now deposited locally rather than carried with the Compton scattered electron. 3.30/MAY-2002...Changed format of data files in order to improve accuracy and performance. GLECS3.3 will only work with the new (3.30) data files. Also made compatible with Darwin/OSX. 3.2/OCT-2001....Minor bug fixes in examp.f for use with g77 compiler. 3.1/SEP-2001....Cleanup of ZEBRA memory allocation. 3.0/JUL-2001....Update for GLECS3.0, which includes full treatment of Rayleigh scattering using tabulated scatter data. 2.0/JUL-2000....First "public" version. 1.0/OCT-1998....First version. 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 author in any publications or presentations that include results using GLECS. LICENSE DISCLAIMER: =================== This program was prepared by the Regents of the University of California at Los Alamos National Laboratory (the University) under contract No. W-7405-ENG-36 with the U.S. Department of Energy (DOE). All rights in the program are reserved by the DOE and the University. Permission is granted to the public to copy and use this software without charge, provided that this Notice and any statement of authorship are reproduced on all copies. Neither the U.S. Government nor the University makes any warranty, express or implied, or assumes any liability or responsibility for the use of this software. -------------------------------------------------------------------------------- -eof-