Provided by: libxray-absorption-perl_3.0.1-4_all bug

NAME

       Xray::Absorption - X-ray absorption data for the elements

SYNOPSIS

          use Xray::Absorption;
          Xray::Absorption -> load("mcmaster");
          $xsec = Xray::Absorption->cross_section('Cu', 9000);

       This example returns the cross section of Copper at 9000 eV using the McMaster tables.

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.

       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

       Because this is an object-oriented approach to X-ray absorption data, you must call
       subroutines as class methods rather than as subroutines:

          $xsec = Xray::Absorption->cross_section('Cu', 9000);

       is correct, but

          $xsec = Xray::Absorption::cross_section('Cu', 9000);

       is incorrect.  Using class methods rather than a function oriented approach allows the
       user of the "Xray::Absorption" module to hot swap absorption data resources.  For example

          foreach $resource (Xray::Absorption->available) {
            Xray::Absorption->load($resource);
            print $resource, " : ",
                  Xray::Absorption->cross_section('Cu', 9000), $/;
          };

       compares the cross section of copper at 9 keV as calculated from the all available data
       resources.

       It is necessary to initialize "Xray::Absorption" to use a particular database by invoking
       the "load" method.  This method establishes and changes inheritance.

METHODS

       "current_resource"
           Example:

              $this = Xray::Absorption -> current_resource;

           Identifies the currently selected resource.

       "in_resource"
           Example:

              $is_there = Xray::Absorption -> in_resource($elem);

           Returns true if $elem is tabulated in the current resource.  $elem can be a two letter
           symbol, the full name of the element, or a Z number.

       "get_energy"
           Example:

              $energy = $energy = Xray::Absorption -> get_energy($elem, $edge);

           Returns the edge energy for $elem.  $edge is one of K, L1, L2, L3, M1, etc.  $edge may
           also be the Siegbahn or IUPAC 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 $elem or
           $edge is an unrecognized symbol, this method returns 0.

       "next_energy"
           Example:

              $next = Xray::Absorption -> next_energy($elem, $edge, @list);

           Given a list of atomic symbols @list, return a list containing the element symbol,
           edge symbol, and energy in eV of the next highest edge energy after the $edge edge of
           $elem.  This returns an empty list if the any argument is unrecognizable.

       "cross_section"
           Examples:

              $xsec = Xray::Absorption -> cross_section($elem, $en, $mode);

              @xsec = Xray::Absorption -> cross_section($elem, \@en, $mode);

           In scalar context, return the cross section in barns/atom of $elem at $energy.  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

              @xsec = Xray::Absorption -> cross_section($elem, \@en, $mode);
              foreach (0 .. $#en) {
                ... do something with energy $xsec[$_] ...
              };

           will be way faster than

              foreach (@en) {
                $xsec = Xray::Absorption -> cross_section($elem, $en, $mode);
                ... do something with $xsec ...
              };

           The optional $mode 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 $mode 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 $mode is not given or is given incorrectly,
           the full cross section is returned.

           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 "get_energy".

       "data_available"
           Example:

              $is_there = Xray::Absorption -> data_available($elem, $edge);

           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.

       "available"
           Example:

              @list = Xray::Absorption -> available;

           Returns a list of all available data resource.

       "scattering"
           Example:

              @list = Xray::Absorption -> scattering;

           Returns a list of all available data resource which contain anomalous scattering
           functions.

       "verbose"
           Example:

              @list = Xray::Absorption -> verbose($arg);

           Turn verbose operation on or off.  If $arg evaluates to true, then warning messages
           will be printed to standard error.  If $arg evaluates to false, then methods will
           silently return 0 when they encounter problems.

       "get_atomic_weight"
           Example:

              $value = Xray::Absorption -> get_atomic_weight($elem);

           Return the atomic weight of $elem.

       "get_density"
           Example:

              $value = Xray::Absorption -> get_density($elem);

           Return the specific gravity of the pure material of $elem.

       "get_conversion"
           Example:

              $value = Xray::Absorption -> get_conversion($elem);

           Return the factor for converting between barns/atom and cm squared/gram for $elem.

       "get_Siegbahn"
           Example:

              $symbol = Xray::Absorption -> get_Siegbahn($sym);

           Return the short Siegbahn symbol for an x-ray fluorescence line.  Thus "Ka1",
           "Kalpha1", and "K-L3" all return "Ka1".  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 "lb2,15" is translated to "lb2".  This returns 0 is
           $sym is not a recognizable symbol for a line.

       "get_Siegbahn_full"
           Example:

              $symbol = Xray::Absorption -> get_Siegbahn_full($sym);

           Return the full Siegbahn symbol for an x-ray fluorescence line.  Thus "Ka1",
           "Kalpha1", and "K-L3" all return "Kalpha1".  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 $sym is not a recognizable symbol
           for a line.

       "get_IUPAC"
           Example:

              $symbol = Xray::Absorption -> get_IUPAC($sym);

           Return the IUPAC symbol for an x-ray fluorescence line.  Thus "Ka1", "Kalpha1", and
           "K-L3" all return "K-L3".  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 $sym is not a recognizable symbol for a line.

       "get_gamma"
           Example:

              $symbol = Xray::Absorption -> get_gamma($sym, $edge);

           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.

       "get_one_minus_g"
           Example:

              $symbol = Xray::Absorption -> get_g($sym, $energy);

           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.

           This term, returned as "1-g" relates the the mass attenuation coefficient, "mu/rho",
           to the mass energy-absorption coefficient, "mu_en/rho", as

               mu_en/rho = (1-g) * mu_tr/rho

           where the mass energy-transfer coefficient, "mu_tr", 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.)

           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.

           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.

           No great care is taken to interpolate correctly around absorption edges.  That should
           be considered a bug.

           This method returns 1 whenever it's imput data is confusing.  That seems safest.

SYMBOLS FOR FLUORESCENCE LINES

       To specify fluorescence lines, Siegbahn or IUPAC 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:

          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

       In addition, the symbols "Lb2,15" and "Lbeta2,15" are recognized as synonyms for "Lbeta2".
       The methods which interpret these symbols will remove spaces and underscores from the
       input string.  Thus "K_alpha_1" and "K a 1" will both be recognized as "Kalpha1".  Since
       hyphens are part of the IUPAC notation, "K-alpha-1" will not be recognized as "Kalpha1".
       Thus use spaces or underscores if you want to make the Siegbahn notation more legible.

ABSORPTION DATA RESOURCES

       Currently, "Xray::Absorption" 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 "Xray::Absorption" module.  It is essential that the new resource take the
       namespace "Xray::Absorption::"Resource, where Resource is a descriptive name, like
       "McMaster" or "Elam".  It is essential that the new resource supply these methods

           current_resource
           in_resource
           get_energy
           next_energy
           cross_section

       and that they use the semantics described above.  All other methods decribed in the last
       section are defined in Absorption.pm and do not need to be redefined in the resource
       modules.

       New resources are welcome to define new methods particular to that data resource in
       addition to the 5 required methods.

UNITS

       All energies returned by the methods of "Xray::Absorption" 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 "get_conversion" method.  Atomic weights are in
       atomic units.  Densities are given as specific gravity (i.e. dimensionless).

BUGS AND THINGS TO DO

       •   Check to be sure things are properly unloaded and overloaded when switching resources.

       •   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.

       •   It would be nice to implement the list that is used by the "next_energy" method as a
           doubly linked list.  In that way, a "previous_energy" method would be trivial.

AUTHOR

       Bruce Ravel <bravel@bnl.gov>

       http://cars9.uchicago.edu/~ravel/software/

LICENCE AND COPYRIGHT

       Copyright (c) 1999-2008 Bruce Ravel (bravel AT bnl DOT gov). All rights reserved.

       This module is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself. See perlartistic.

       This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
       without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.