.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Xray::Absorption 3pm" .TH Xray::Absorption 3pm "2015-08-20" "perl v5.20.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Xray::Absorption \- X\-ray absorption data for the elements .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& use Xray::Absorption; \& Xray::Absorption \-> load("mcmaster"); \& $xsec = Xray::Absorption\->cross_section(\*(AqCu\*(Aq, 9000); .Ve .PP This example returns the cross section of Copper at 9000 eV using the McMaster tables. .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module supports access to X\-ray absorption data. It is designed to be a transparent interface to absorption data from a variety of sources. Currently, the only sources of data are the 1969 McMaster tables, the 1999 Elam tables, the 1993 Henke tables, and the 1995 Chantler tables. The Brennan-Cowen implementation of the Cromer-Liberman tables is available as a drop-on-top addition to this package. More resources can be added easily. .PP Information used to compute the mass energy-absorption coefficient is taken from the tabulations of Hubbell and Seltzer: http://physics.nist.gov/PhysRefData/XrayMassCoef/cover.html .PP Because this is an object-oriented approach to X\-ray absorption data, you must call subroutines as class methods rather than as subroutines: .PP .Vb 1 \& $xsec = Xray::Absorption\->cross_section(\*(AqCu\*(Aq, 9000); .Ve .PP is correct, but .PP .Vb 1 \& $xsec = Xray::Absorption::cross_section(\*(AqCu\*(Aq, 9000); .Ve .PP is incorrect. Using class methods rather than a function oriented approach allows the user of the \f(CW\*(C`Xray::Absorption\*(C'\fR module to \fIhot swap\fR absorption data resources. For example .PP .Vb 5 \& foreach $resource (Xray::Absorption\->available) { \& Xray::Absorption\->load($resource); \& print $resource, " : ", \& Xray::Absorption\->cross_section(\*(AqCu\*(Aq, 9000), $/; \& }; .Ve .PP compares the cross section of copper at 9 keV as calculated from the all available data resources. .PP It is necessary to initialize \f(CW\*(C`Xray::Absorption\*(C'\fR to use a particular database by invoking the \f(CW\*(C`load\*(C'\fR method. This method establishes and changes inheritance. .SH "METHODS" .IX Header "METHODS" .ie n .IP """current_resource""" 4 .el .IP "\f(CWcurrent_resource\fR" 4 .IX Item "current_resource" Example: .Sp .Vb 1 \& $this = Xray::Absorption \-> current_resource; .Ve .Sp Identifies the currently selected resource. .ie n .IP """in_resource""" 4 .el .IP "\f(CWin_resource\fR" 4 .IX Item "in_resource" Example: .Sp .Vb 1 \& $is_there = Xray::Absorption \-> in_resource($elem); .Ve .Sp Returns true if \f(CW$elem\fR is tabulated in the current resource. \&\f(CW$elem\fR can be a two letter symbol, the full name of the element, or a Z number. .ie n .IP """get_energy""" 4 .el .IP "\f(CWget_energy\fR" 4 .IX Item "get_energy" Example: .Sp .Vb 1 \& $energy = $energy = Xray::Absorption \-> get_energy($elem, $edge); .Ve .Sp Returns the edge energy for \f(CW$elem\fR. \f(CW$edge\fR is one of K, L1, L2, L3, M1, etc. \f(CW$edge\fR may also be the Siegbahn or \s-1IUPAC\s0 symbol for a fluorescence line. Some data resources provide more lines than others. Some may provide no lines at all. See the documentation for each resource for which lines are available. When either \f(CW$elem\fR or \&\f(CW$edge\fR is an unrecognized symbol, this method returns 0. .ie n .IP """next_energy""" 4 .el .IP "\f(CWnext_energy\fR" 4 .IX Item "next_energy" Example: .Sp .Vb 1 \& $next = Xray::Absorption \-> next_energy($elem, $edge, @list); .Ve .Sp Given a list of atomic symbols \f(CW@list\fR, return a list containing the element symbol, edge symbol, and energy in eV of the next highest edge energy after the \f(CW$edge\fR edge of \f(CW$elem\fR. This returns an empty list if the any argument is unrecognizable. .ie n .IP """cross_section""" 4 .el .IP "\f(CWcross_section\fR" 4 .IX Item "cross_section" Examples: .Sp .Vb 1 \& $xsec = Xray::Absorption \-> cross_section($elem, $en, $mode); \& \& @xsec = Xray::Absorption \-> cross_section($elem, \e@en, $mode); .Ve .Sp In scalar context, return the cross section in barns/atom of \f(CW$elem\fR at \f(CW$energy\fR. In list context, return a list of cross-sections given a reference to a list of energies. For some data resources, list context may be significantly faster than repeated calls in scalar context, i.e. this .Sp .Vb 4 \& @xsec = Xray::Absorption \-> cross_section($elem, \e@en, $mode); \& foreach (0 .. $#en) { \& ... do something with energy $xsec[$_] ... \& }; .Ve .Sp will be way faster than .Sp .Vb 4 \& foreach (@en) { \& $xsec = Xray::Absorption \-> cross_section($elem, $en, $mode); \& ... do something with $xsec ... \& }; .Ve .Sp The optional \f(CW$mode\fR argument tells this method what kind of data to return. The default for all data resources is to return the cross section, however each resource has several other option. For example, the McMaster tables offer along with the absorption cross section, the coherent scattering, the incoherent scattering, or the sum of the three contributions. The allowed values for \f(CW$mode\fR depend on the data contained in the absorption resource currently loaded, but the default is always to return the photoelectron cross section, or the full cross section if the coherent and incoherent scattering portions are included in the resource. See the documentation for the individual resource modules. If \f(CW$mode\fR is not given or is given incorrectly, the full cross section is returned. .Sp If an energy is requested which is right on an edge, all data resources assume that you want the cross-section just above the edge. The granularity of the comparison between the requested energy and the edge energy is 1 milivolt, so if you want a cross-section just below an edge, you should request an energy that is more than 1 milivolt less than the value returned by \f(CW\*(C`get_energy\*(C'\fR. .ie n .IP """data_available""" 4 .el .IP "\f(CWdata_available\fR" 4 .IX Item "data_available" Example: .Sp .Vb 1 \& $is_there = Xray::Absorption \-> data_available($elem, $edge); .Ve .Sp Returns true if the selected resource contains sufficient data for handling the specified element in the energy range around the specified edge. Returns false otherwise. .ie n .IP """available""" 4 .el .IP "\f(CWavailable\fR" 4 .IX Item "available" Example: .Sp .Vb 1 \& @list = Xray::Absorption \-> available; .Ve .Sp Returns a list of all available data resource. .ie n .IP """scattering""" 4 .el .IP "\f(CWscattering\fR" 4 .IX Item "scattering" Example: .Sp .Vb 1 \& @list = Xray::Absorption \-> scattering; .Ve .Sp Returns a list of all available data resource which contain anomalous scattering functions. .ie n .IP """verbose""" 4 .el .IP "\f(CWverbose\fR" 4 .IX Item "verbose" Example: .Sp .Vb 1 \& @list = Xray::Absorption \-> verbose($arg); .Ve .Sp Turn verbose operation on or off. If \f(CW$arg\fR evaluates to true, then warning messages will be printed to standard error. If \f(CW$arg\fR evaluates to false, then methods will silently return 0 when they encounter problems. .ie n .IP """get_atomic_weight""" 4 .el .IP "\f(CWget_atomic_weight\fR" 4 .IX Item "get_atomic_weight" Example: .Sp .Vb 1 \& $value = Xray::Absorption \-> get_atomic_weight($elem); .Ve .Sp Return the atomic weight of \f(CW$elem\fR. .ie n .IP """get_density""" 4 .el .IP "\f(CWget_density\fR" 4 .IX Item "get_density" Example: .Sp .Vb 1 \& $value = Xray::Absorption \-> get_density($elem); .Ve .Sp Return the specific gravity of the pure material of \f(CW$elem\fR. .ie n .IP """get_conversion""" 4 .el .IP "\f(CWget_conversion\fR" 4 .IX Item "get_conversion" Example: .Sp .Vb 1 \& $value = Xray::Absorption \-> get_conversion($elem); .Ve .Sp Return the factor for converting between barns/atom and cm squared/gram for \f(CW$elem\fR. .ie n .IP """get_Siegbahn""" 4 .el .IP "\f(CWget_Siegbahn\fR" 4 .IX Item "get_Siegbahn" Example: .Sp .Vb 1 \& $symbol = Xray::Absorption \-> get_Siegbahn($sym); .Ve .Sp Return the short Siegbahn symbol for an x\-ray fluorescence line. Thus \&\*(L"Ka1\*(R", \*(L"Kalpha1\*(R", and \*(L"K\-L3\*(R" all return \*(L"Ka1\*(R". The case of the input symbol does not matter and the symbol is returned capitalized. White space and underscores will be removed from the input symbol. The symbol \*(L"lb2,15\*(R" is translated to \*(L"lb2\*(R". This returns 0 is \f(CW$sym\fR is not a recognizable symbol for a line. .ie n .IP """get_Siegbahn_full""" 4 .el .IP "\f(CWget_Siegbahn_full\fR" 4 .IX Item "get_Siegbahn_full" Example: .Sp .Vb 1 \& $symbol = Xray::Absorption \-> get_Siegbahn_full($sym); .Ve .Sp Return the full Siegbahn symbol for an x\-ray fluorescence line. Thus \&\*(L"Ka1\*(R", \*(L"Kalpha1\*(R", and \*(L"K\-L3\*(R" all return \*(L"Kalpha1\*(R". The case of the input symbol does not matter and the symbol is returned capitalized. White space and underscores will be removed from the input symbol. This returns 0 is \f(CW$sym\fR is not a recognizable symbol for a line. .ie n .IP """get_IUPAC""" 4 .el .IP "\f(CWget_IUPAC\fR" 4 .IX Item "get_IUPAC" Example: .Sp .Vb 1 \& $symbol = Xray::Absorption \-> get_IUPAC($sym); .Ve .Sp Return the \s-1IUPAC\s0 symbol for an x\-ray fluorescence line. Thus \*(L"Ka1\*(R", \&\*(L"Kalpha1\*(R", and \*(L"K\-L3\*(R" all return \*(L"K\-L3\*(R". The case of the input symbol does not matter and the symbol is returned in all capitals. White space and underscores will be removed from the input symbol. This returns 0 is \f(CW$sym\fR is not a recognizable symbol for a line. .ie n .IP """get_gamma""" 4 .el .IP "\f(CWget_gamma\fR" 4 .IX Item "get_gamma" Example: .Sp .Vb 1 \& $symbol = Xray::Absorption \-> get_gamma($sym, $edge); .Ve .Sp Return an approximation of the core-hole lifetime for the given atomic symbol and edge. This follows Feff very closely. In fact the data used is swiped from the setgam subroutine in Feff, which is in turn swiped from K. Rahkonen and K. Krause, Atomic Data and Nuclear Data Tables, Vol 14, Number 2, 1974. The values given by this routine are a bit different from those given by Feff since a different interpolation is used. For O and P edges a value of 0.1 is returned, as in Feff. If the arguments are not interpretable, a value of 0 is returned. .ie n .IP """get_one_minus_g""" 4 .el .IP "\f(CWget_one_minus_g\fR" 4 .IX Item "get_one_minus_g" Example: .Sp .Vb 1 \& $symbol = Xray::Absorption \-> get_g($sym, $energy); .Ve .Sp Return an approximation of the factor required to translate tabulated cross-section data to the mass energy-absorption coefficient, as described by Hubbell at http://physics.nist.gov/PhysRefData/XrayMassCoef/cover.html. .Sp This term, returned as \f(CW\*(C`1\-g\*(C'\fR relates the the mass attenuation coefficient, \f(CW\*(C`mu/rho\*(C'\fR, to the mass energy-absorption coefficient, \&\f(CW\*(C`mu_en/rho\*(C'\fR, as .Sp .Vb 1 \& mu_en/rho = (1\-g) * mu_tr/rho .Ve .Sp where the mass energy-transfer coefficient, \f(CW\*(C`mu_tr\*(C'\fR, is the sum of the photoabsorption and incoherent cross-sections. (At the energies at which this module is applicable, other cross-sections such as pair production can be ignored.) .Sp So, to use this factor, compute the sum of the photoabsorption and incoherent cross-sections at some energy and multiply by the number this method returns. .Sp The importance of this term depends on energy and on element. For nitrogen, for example, this term becomes increasingly important above 10 keV. For argon, it is near unity up to about 30 keV. .Sp No great care is taken to interpolate correctly around absorption edges. That should be considered a bug. .Sp This method returns 1 whenever it's imput data is confusing. That seems safest. .SH "SYMBOLS FOR FLUORESCENCE LINES" .IX Header "SYMBOLS FOR FLUORESCENCE LINES" To specify fluorescence lines, Siegbahn or \s-1IUPAC\s0 symbols may be used. methods are provided for converting between these notations. The Siegbahn notations can be in the short or full forms. Here is a table of all recognized symbols: .PP .Vb 10 \& Full Siegbahn Short Siegbahn IUPAC \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& Kalpha1 Ka1 K\-L3 \& Kalpha2 Ka2 K\-L2 \& Kalpha3 Ka3 K\-L1 \& Kbeta1 Kb1 K\-M3 \& Kbeta2 Kb2 K\-N2,3 \& Kbeta3 Kb3 K\-M2 \& Kbeta4 Kb4 K\-N4,5 \& Kbeta5 Kb5 K\-M4,5 \& Lalpha1 La1 L3\-M5 \& Lalpha2 La2 L3\-M4 \& Lbeta1 Lb1 L2\-M4 \& Lbeta2 Lb2 L3\-N4,5 \& Lbeta3 Lb3 L1\-M3 \& Lbeta4 Lb4 L1\-M2 \& Lbeta5 Lb5 L3\-O4,5 \& Lbeta6 Lb6 L3\-N1 \& Lgamma1 Lg1 L2\-N4 \& Lgamma2 Lg2 L1\-N2 \& Lgamma3 Lg3 L1\-N3 \& Lgamma6 Lg6 L2\-O4 \& Ll Ll L3\-M1 \& Lnu Ln L2\-M1 \& Malpha Ma M5\-N6,7 \& Mbeta Mb M4\-N6 \& Mgamma Mg M3\-N5 \& Mzeta Mz M4,5\-N6,7 .Ve .PP In addition, the symbols \f(CW\*(C`Lb2,15\*(C'\fR and \f(CW\*(C`Lbeta2,15\*(C'\fR are recognized as synonyms for \f(CW\*(C`Lbeta2\*(C'\fR. The methods which interpret these symbols will remove spaces and underscores from the input string. Thus \&\f(CW\*(C`K_alpha_1\*(C'\fR and \f(CW\*(C`K a 1\*(C'\fR will both be recognized as \f(CW\*(C`Kalpha1\*(C'\fR. Since hyphens are part of the \s-1IUPAC\s0 notation, \f(CW\*(C`K\-alpha\-1\*(C'\fR will not be recognized as \f(CW\*(C`Kalpha1\*(C'\fR. Thus use spaces or underscores if you want to make the Siegbahn notation more legible. .SH "ABSORPTION DATA RESOURCES" .IX Header "ABSORPTION DATA RESOURCES" Currently, \f(CW\*(C`Xray::Absorption\*(C'\fR has the McMaster, Elam, Henke, and Chantler tables as its data resources. New resources may be added over time. This section offers a few guidelines to anyone interested in supplying more resources. It does not matter how the new resource calculates the cross section. That is hidden behind the object-orientedness of the \f(CW\*(C`Xray::Absorption\*(C'\fR module. It is essential that the new resource take the namespace \&\f(CW\*(C`Xray::Absorption::\*(C'\fR\fIResource\fR, where \fIResource\fR is a descriptive name, like \f(CW\*(C`McMaster\*(C'\fR or \f(CW\*(C`Elam\*(C'\fR. It is essential that the new resource supply these methods .PP .Vb 5 \& current_resource \& in_resource \& get_energy \& next_energy \& cross_section .Ve .PP and that they use the semantics described above. All other methods decribed in the last section are defined in \fIAbsorption.pm\fR and do not need to be redefined in the resource modules. .PP New resources are welcome to define new methods particular to that data resource in addition to the 5 required methods. .SH "UNITS" .IX Header "UNITS" All energies returned by the methods of \f(CW\*(C`Xray::Absorption\*(C'\fR are in electron volts. All cross sections are in units of barns per atom. A conversion constant between that unit and cm squared per gram is supplied by the \f(CW\*(C`get_conversion\*(C'\fR method. Atomic weights are in atomic units. Densities are given as specific gravity (i.e. dimensionless). .SH "BUGS AND THINGS TO DO" .IX Header "BUGS AND THINGS TO DO" .IP "\(bu" 4 Check to be sure things are properly unloaded and overloaded when switching resources. .IP "\(bu" 4 Test for pathelogical cases, such as elements that don't exist, that have Z's in the hundreds, energies that are very low or very high, and so on. .IP "\(bu" 4 It would be nice to implement the list that is used by the \&\f(CW\*(C`next_energy\*(C'\fR method as a doubly linked list. In that way, a \&\f(CW\*(C`previous_energy\*(C'\fR method would be trivial. .SH "AUTHOR" .IX Header "AUTHOR" Bruce Ravel .PP http://cars9.uchicago.edu/~ravel/software/ .SH "LICENCE AND COPYRIGHT" .IX Header "LICENCE AND COPYRIGHT" Copyright (c) 1999\-2008 Bruce Ravel (bravel \s-1AT\s0 bnl \s-1DOT\s0 gov). All rights reserved. .PP This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic. .PP This program is distributed in the hope that it will be useful, but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0