!	Help file for the new DCL command ABSORPTION

1 ABSORPTION
    Calculates f' and f'' based on theoretical work of Cromer and Liberman
and calculates Rayleigh and Compton cross-section based on McMaster.
Calculated values are only moderately accurate near an absorption edge due
to chemical effects and EXAFS.  Hydrogen and Helium data are McMasters for 
photo-electric effect as well as Rayleigh and Compton.  Data available to 
user-written routines from shareable image library.  Also available are 
form factor tables for calculating f(k) using theoretical work of Cromer 
and Mann.  See ABS$SFCOEF in subroutine library.  Structure Factors are
available (see ABS$STRUCT_FACT).  Absorption edge energies and fluoresence
lines listed too. f' correction from Kissel now included.

2 CRYSTALS AND MATERIALS

	If you enter 1 or 2 characters the program expects an element.  More
than that and it looks first for a crystal (.LAT file) and second for
a material (.MTL file).  See ABS$ABSORB to use the same routine in user-
called programs.


2 Literature_references
	D.T. Cromer, Acta Cryst 18, 17,(1965).
	D.T. Cromer and D. Liberman, J. Chem. Phys. 53, 1891 (1970).
	D.T. Cromer and D.A. Liberman, Acta Cryst A37, 267 (1981).
	UCRL-50174 SEC II REV I W.H. McMaster, N. Kerr Del Grande,
	    J.H. Mallett and J.H. Hubbell, from NTIS, USDOC.
	Cromer and Mann, Acta Cryst A24 321 (1968).  (form factor)
	Balyuzi, Acta Cryst A31, 600 (1975).	(Compton form factor)
    Kissel (Acta Cryst A46, 170 (1990))  (f' correction term)
	This package is described in
	S. Brennan and P.L. Cowan
	"A suite of programs for calculating x-ray absorption, reflection and
	diffraction performance for a variety of materials at arbitrary 
	wavelengths" Rev. Sci. Instrum., 63, 850 (1992).
	

2 DCL_command
	You can use ABSORPTION in one of two ways.

	a) As a one line command, as $ ABSORPTION SI 5000 20, which shows
the absorption for Silicon at 5000eV and thickness 20 microns.  Note that
if the second and third parameters aren't present, they default to 8000 eV
and 100 microns.

	b) As a multi-line command, as $ABSORPTION. You will then be
prompted for input, and can specify parameters iteratively.

2 Subroutine_library
	The subroutine used by the ABSORPTION DCL command are available
for use by user-written programs.  Because they are in a shareable image
library you need not explicitly link to them.

3 ABS$ABSORB
	Calling format (FORTRAN)
	CALL ABS$ABSORB( NAME, NAM_LEN, ENERGY, MU, RHO, IFAIL)
	CHARACTER*(*) NAME
	INTEGER*4 NAM_LEN, IFAIL
	REAL*4 ENERGY, MU, RHO
with
NAME	(read-only)	name of the file which defines the crystal
NAM_LEN	(read-only)	length of the name string
ENERGY	(read-only)	energy in eV at which the absorption is calculated
MU	(write-only)	absorption in 1/microns
RHO	(write-only)	density in gms/cm^3
IFAIL (write-only)  0 if ok, 1 if there was a problem
This routine parses the name as follows: if 1 or 2 characters, it attempts
to parse it as an element.  If longer than 2 characters, it first trys to
find a crystal lattice file, next a material file.

3 ABS$ATOMIC_DATA
	Calling format (FORTRAN):

	CALL ABS$ATOMIC_DATA( ZED, AMU, RHO, N_EDGE, ABS_EDGE)
	INTEGER*4 ZED, N_EDGE
	REAL*4 AMU, RHO, ABS_EDGE(24)
with
ZED	(read-write)		Element number
This is returned as zero if it is out of range (>92)
AMU	(write-only)		Atomic Weight
RHO	(write-only)		Density in grams/cc
N_EDGE	(write-only)	number of absorption edges for this element
ABS_EDGE	(write-only)
	Absorption Edge energies, K-edge first, then L-III, L-II, etc.

3 ABS$CROMER
	Calling format (FORTRAN):

	CALL ABS$CROMER( ZED, ENERGY, FP, FPP)
	INTEGER*4 ZED
	REAL*4 ENERGY, FP, FPP
with
ZED	(read-write)		Element number
This is returned as zero if it is out of range (>92)
ENERGY	(read-only)		Energy IN EV for the calculation
If the energy is below the lowest absorption edge of the element, FPP
returns 0., so be sure that its eV, not keV, and don't go too low in 
energy.
FP	(write-only)		F' in electrons
FPP	(write-only)		F'' in electrons

This routine calculates photoelectric f' and f" based on Cromer&Liberman

3 ABS$CRYS_ABS
	Calling format (FORTRAN)
	CALL ABS$CRYS_ABS( NAME, NAM_LEN, ENERGY, MU, RHO, IFAIL)
	CHARACTER*(*) NAME
	INTEGER*4 NAM_LEN, IFAIL
	REAL*4 ENERGY, MU, RHO
with
NAME	(read-only)	name of the file which defines the crystal
NAM_LEN	(read-only)	length of the name string
ENERGY	(read-only)	energy in eV at which the absorption is calculated
MU	(write-only)	absorption in 1/microns
RHO	(write-only)	density in gms/cm^3
IFAIL (write-only)  0 if ok, 1 if there was a problem

3 ABS$ELEMENT
	Calling format (FORTRAN):

	CALL ABS$ELEMENT( ZED, SYMBOL)
	INTEGER*4 ZED
	CHAR*2 SYMBOL
with
ZED	(Read-write)
	If ZED < 0, then SYMBOL is passed to subroutine by calling routine
to test its validity. If valid, the returned value of ZED is the (positive)
Element number of the symbol specified.
	If ZED = 0 then subroutine prompts you (using the process defined
files SYS$INPUT and SYS$OUTPUT) for the value of SYMBOL. If value entered
is invalid, then ZED is returned as zero.
	If 1<ZED<92 then SYMBOL is returned accordingly.

SYMBOL	(Read-write)
	If ZED < 0, SYMBOL is translated to upper case.
	If ZED = 0, SYMBOL is read from SYS$INPUT and translated to upper
	case.	

3 ABS$GET_CRYSTAL_DATA
	Get data from crystal lattice common blocks for manipulation 
prior to calling ABS$STRUCT_FACT.
	Calling format (FORTRAN)
	CALL ABS$GET_CRYSTAL_DATA( BASIS, NATOMS, ZED, FRACT
	1	, A_ZERO, B_ZERO, C_ZERO, NSTIFF, STIFF)
	REAL*4 FRACT(20,5), A_ZERO, B_ZERO, C_ZERO, STIFF(10)
	INTEGER*4 BASIS, NATOMS(20), ZED(20,5), NSTIFF
All variables are write-only, i.e. are returned by the subroutine.
BASIS	Number of different bases in the crystal
NATOMS	Array of number of different atomic species in each basis
ZED	Array of atomic numbers in each basis, upto 5 z's per basis
FRACT	Array of the fraction of each Z in each basis. Sum of fract= 1.
A_ZERO	Lattice parameter
B_ZERO	Lattice parameter
C_ZERO	Lattice parameter
NSTIFF	Number of stiffness parameters
STIFF	Array of stiffness parameters
ABS$RDLATTICE must be called before this routine can be called.

3 ABS$GET_CRYSTAL2_DATA
	Get information about a second crystal lattice without writing into
common blocks used by ABS$STRUCT_FACT.
	Calling format (FORTRAN)
	CALL ABS$GET_CRYSTAL2_DATA( NCHRS, CRYS_NAME, BASIS, NATOMS
	1	, ZED, FRACT, A_ZERO, B_ZERO, C_ZERO, NSTIFF, STIFF
	1	, NOREAD)
	INTEGER*4 NCHRS, BASIS, NSTIFF, NOREAD, NATOMS(20), ZED(20,5)
	REAL*4 FRACT(20,5), A_ZERO, B_ZERO, C_ZERO, STIFF(10)
	CHARACTER*(*) CRYS_NAME
NCHRS		(read-only) Length of lattice file name
CRYS_NAME	(read-only) Character string of lattice file name
All others are write-only, i.e. modified by subroutine
BASIS	Number of different bases in the crystal
NATOMS	Array of number of different atomic species in each basis
ZED	Array of atomic numbers in each basis, upto 5 z's per basis
FRACT	Array of the fraction of each Z in each basis. Sum of fract= 1.
A_ZERO	Lattice parameter
B_ZERO	Lattice parameter
C_ZERO	Lattice parameter
NSTIFF	Number of stiffness parameters
STIFF	Array of stiffness parameters
NOREAD	Integer returned 0 if file opened ok, 1 if error on open

3 ABS$GET_STRING
	Calling format (FORTRAN):
	CALL ABS$GET_STRING( STRING, NCHRS)
	INTEGER*4 NCHRS
	CHARACTER*(*) STRING
with
STRING (write-only)	Character string
NCHRS  (write-only) number of characters in STRING.  If there is an error
on read, (or a CTRLZ typed), NCHRS is returned as -1.
	
3 ABS$LOW_UP( STRING, NCHRS)
	Calling sequence (FORTRAN)
	CALL ABS$LOW_UP( STRING, NCHRS)
	INTEGER*4 NCHRS
	CHARACTER*(*) STRING
with
STRING (read-write) Character string which, if it contains lower-case
(a-z) will be replaced with upper-case (A-Z).
NCHRS  (read-only)  number of characters in STRING.  If nchrs </= 0,
STRING returned without change.

3 ABS$MASS_ABS
	Calling format (FORTRAN):
	CALL ABS$MASS_ABS( ZED, ENERGY, MU, RHO)
	INTEGER*4 ZED
	REAL*4 MU, ENERGY, RHO
with
ZED	(read-write)
This is returned as zero if out of range (>92)
ENERGY	(read-only)		Energy IN EV for the calculation
MU	(write-only)		Absorption cross-section, in 1/microns
NOTE: MU HAS BEEN CHANGED FROM MU_ON_RHO IN THIS RELEASE FOR CONSISTENCY 
WITH ABS$MATL_ABS AND ABS$CRYS_ABS
RHO	(read-only)	Density (gms/cm^3)

This is a courtesy routine which returns the mass absorption coefficient
in 1/cm, and also returns the density (in gms/cm^3) as stored in the
data base.  It makes the necessary calls to the other routines for you.

3 ABS$MATL_ABS
	Calling format (FORTRAN)
	CALL ABS$MATL_ABS( NAME, NAM_LEN, ENERGY, MU, RHO, IFAIL)
	CHARACTER*(*) NAME
	INTEGER*4 NAM_LEN, IFAIL
	REAL*4 ENERGY, MU, RHO
with
NAME	(read-only)	name of the file which defines the material
NAM_LEN	(read-only)	length of the name string
ENERGY	(read-only)	energy in eV at which the absorption is calculated
MU	(write-only)	absorption in 1/microns
RHO	(write-only)	density in gms/cm^3
IFAIL (write-only)  0 if ok, 1 if there was a problem

3 ABS$RAYCOMP
	Calling format (FORTRAN):

	CALL ABS$RAYCOMP( ZED, ENERGY, RAY, COMP)
	INTEGER*4 ZED
	REAL*4 ENERGY, RAY, COMP
with
ZED	(read-write)		Element number
This is returned as zero if it is out of range (>92)
ENERGY	(read-only)		Energy IN EV for the calculation
RAY	(write-only)		Rayleigh term, in electrons
COMP	(write-only)		Compton term, in electrons

This routine calculates the Rayleigh and Compton cross-sections based on
LN-LN fits published by McMasters et al., (1969).

3 ABS$RDLATTICE
	Calling format (FORTRAN)
	CALL ABS$RDLATTICE( NAME, NAM_LEN, NOREAD)
	CHARACTER*(*) NAME
	INTEGER*4 NAM_LEN, NOREAD
NAME	(read-only)	name of the file which defines the crystal
NAM_LEN	(read-only)	length of the name string
NOREAD	(write-only)	zero if file was read ok, 1 if there was a problem
This routine must be called before ABS$STRUCT_FACT is called.

3 ABS$SET_CRYSTAL_DATA
	Put lattice parameters and number and fraction of each elements 
into the common blocks prior to calling ABS$STRUCT_FACT
	Calling format (FORTRAN)
	CALL ABS$SET_CRYSTAL_DATA( NATOMS, ZED, FRACT, A_ZERO, B_ZERO
	1	, C_ZERO)
	INTEGER*4 NATOMS(20), ZED(20,5)
	REAL*4 FRACT(20,5), A_ZERO, B_ZERO, C_ZERO
All variables are read-only, i.e. not modified by the subroutine
NATOMS	Array of number of different atomic species in each basis
ZED	Array of atomic numbers in each basis, upto 5 z's per basis
FRACT	Array of the fraction of each Z in each basis. Sum of fract= 1.
A_ZERO	Lattice parameter
B_ZERO	Lattice parameter
C_ZERO	Lattice parameter
ABS$RDLATTICE must be called before this routine can be called.

3 ABS$SFCOEF
	Calling format (FORTRAN)
	SCAT_FACT= ABS$SFCOEF( ZED, K, COMP)
	INTEGER*4 ZED
	REAL*4 ABS$SFCOEF, K, COMP
with
SCAT_FACT	Scattering factor, in electrons
ZED	(read-only)	Element number
K	(read-only)	Scattering vector (units = 4*pi*sin(theta)/lambda)
COMP	(write-only)	Compton component, in electrons

This function is based on the theoretical work of 
	Cromer and Mann, Acta Cryst A24 321 (1968).
Compton term based on fits of 
	Balyuzi, Acta Cryst A31, 600 (1975).
The data file is separate from those used for the absorption 
cross-sections. 

3 ABS$STRUCT_FACT
	Calling format (FORTRAN)
	REAL*4 H, K, L, ENERGY, T_CRYST, RHO, VOL, THETAB, GAMMA
	REAL*8 D_SPACE
	COMPLEX*16 CD_STRF
	INTEGER*4 IPOL
	CALL ABS$STRUCT_FACT( H, K, L, ENERGY, IPOL, T_CRYST, CD_STRF
	1	, THETAB, GAMMA, D_SPACE, RHO, VOL)
H,K,L	(read-only)	Miller indeces.  can be all zero to get F(0)
ENERGY	(read-only)	Energy in eV
IPOL	(read-only)	Polarization.  1= sigma, 2= pi.
T_CRYST	(read-only)	Crystal temperature(K). Room Temp= 293.
CD_STRF	(write-only)	complex Structure factor
THETAB  (write-only)	Bragg angle (in degrees)
GAMMA	(write-only)	Factor for converting from F to Chi
D_SPACE	(write-only)	dspacing of the planes defined by h,k,l
RHO	(write-only)	density of the crystal (gms/cc)
VOL	(write-only)	size of the crystal in Angstroms^3.
ABS$RDLATTICE must be called before this is called.

3 Example_driver_program
	The Fortran code ABSORB.F is in SYS$EXAMPLES:
This program shows how to use CLD files, and shows the conversion from
the anomalous scattering factor f'' to mu, the absorption coefficient.

2 Credits
	This program was written by Sean Brennan at SSRL. The original
batch version (on punch cards, no less!) was obtained from D.T. Cromer.
Much help from T. Cox in turning it into a shareable image library.
Significant help and bug-squashing by Paul Cowan of Argonne Natl. Lab.
Divide by zero errors solved by Chris Chantler of NIST.

2 Revision_history
3 V1.0
	This is the first production release
3 V1.1
	Shareable image library entry points ABS$CROMER, ABS$ATOMIC_DATA 
and ABS$ELEMENT added
3 V1.2
	Minor bug-squashing
3 V1.3
	Compton and elastic cross-sections accessable using ABS$RAYCOMP in
shareable image library.  ABS$MASS_ABS returns the mass absorption 
coefficient (in cm^2/gram) and the density.  ABS$SFCOEF routine added for 
form factor calculations.
3 V2.0
	Addition of Material Files and Crystal files.  Structure Factor 
calculations strongly indebted to P.L. Cowan.  Divide by zero errors solved 
by Chris Chantler of NIST.  ABS$MASS_ABS changed to return mu rather than
mu_on_rho.  Now consistent with ABS$MATL_ABS and ABS$CRYS_ABS.
3 V3.0
    Data bases now part of program, no longer separate data files.  All
VMS calls removed.  ABS$RDLATTICE modified ( ( string, len) instead of
(len, string)) to be consistent with ABS$MATL_ABS, ABS$CRYS_ABS.
ABS$ABSORB which parses string as element, crystal or material.  Material
files changed to extension .MTL to avoid conflict with MATLAB files.
3 v3.1
    Jensen and Ludwig corrections to f' replaced by Kissel correction
table thanks to Todd Hufnagel.  Minor bug squashing (density for Rn 
corrected).  
