This appendix reproduces the documentation contained in the perl modules that come with the ATOMS distributions. This appendix is mostly useful to the person interested modifying some part of ATOMS or in using these modules to write new programs.
use Xray::Xtal;
use Xray::Atoms qw(parse_input keyword_defaults parse_atp
absorption mcmaster);
There are several versions of Atoms with different user interfaces all of which use routines from this module. These include the command line, Tk, and CGI versions.
To simplify the handling of input data, this module provides an object. It is used like this:
my $keywords = Xray::Atoms -> new();
$keywords -> make('rmax' => 5.7)
The make method is the general way of storing data in the keywords object. In general, this method assumes that the keyword takes a scalar value. The data structure is just a hash, so the keyword can be anything. Indeed, keyword recognition is not done in this module. Keyword/value pairs are just blindly stored for later processing. Several keywords are treated specially because they are commonly used in the programs included in the Atoms package. These keywords
a b c alpha beta gamma argon krypton nitrogen rmax
are treated as numbers. This means that they are eval-ed (and so can be short expressions like 1/2 or 3.5+0.001) and return 0 if they cannot be interpreted as numbers. This evaluation is done in a taint-safe manner.
A couple of keywords are treated specially.
$keywords -> make(title=>'This is a title!');
pushes the given string onto an anonymous array of strings. In this way, any number of title lines can be kept in the object.
The shift keyword is also handled specially. This takes three arguments, the three components of the shift vector. A syntax like this works fine:
$keywords -> make('shift' => $x, $y, $z);
This stores the three values of the shift vector as an anonymous array.
This method is used by atoms to read an atoms input file. It is typically called by
$keywords -> parse_input($file, 0);
The first argument is the name of the input file. The second argument is tells the error trapping mechnism what kind of environment you are working in. If you have written a command-line program, it should be 0. In a Tk program, it should 1. In a CGI script it should be 2.
The contents of the file are parsed and stored in a keywords object. The method is fairly clever about interpreting the file and offering warning and error messages. It uses a Safe compartment to evaluate unique atoms positions, thus allowing simple math expressions to be used in the atom list.
This method is used to perform some sanity checks on the keyword values after reading in the input data and populating the sites and the cell. It is a good idea to call this before building a cluster or starting some other calculation.
$keywords -> verify_keywords(\$cell, \@sites, 0, 0);
The first two arguments are references to the Cell object and to a list of Site objects. The third argument is the same as the second argument to the parse_input method. The last argument should be non-zero only for a calculation that does not need to know which is the central atom (e.g. a powder diffraction simulation).
This is a subroutine rather than a method, so that is can be used even without an active keywords object. It is a wrapper for generating error and warning methods that will work in command-line, GUI, and CGI environments.
$keywords -> warn_or_die("This is a warning message", $die);
The first argument is the actual message. The die argument is 0, 1, or 2 as described for parse_input. The final argument is a keywords object and is only used in the CGI environment. In that case, here are no convenient output or error channels, so messages are stored in the keywords hash as a single string under the key "www_
This subroutine is the output engine. It parses the appropriate atp file, interprets its content, and generates output data. This one subroutine handles the creation of feff.inp and the other sorts of lists generated by Atoms. It also generates reports for the Absorption notecard in TkAtoms and for the lists describing the DAFS calculation as a function of energy and the powder calculation as a function of angle. Essentially all output from all programs that come with the Atoms package is generated here.
my ($default_name, $is_feff) =
&parse_atp($atp, \$cell, \$keywords, \@cluster, \@neutral, \$contents);
open (INP, ">".$default_name) or die $!;
print INP $contents;
close INP;
The arguments are
Typically the contents variables is the things written to the output channel. The two return values are the default name for the output file and a flag indicating whether the output is intended to run FEFF. Both of these pieces of information are read from the meta line of the atp file.
This subroutine calculates the total absorption (or one over the e-fold absorption length), the delta_
This subroutine calculates the total absorption (or one over the e-fold absorption length) and the specific gravity of the crystal at a specified energy (rather than around the edge energy of an element).
($total_absorption, $specific_gravity) =
&xsec(\$cell, $central, $energy);
The input arguments are a reference to a populated cell, the tag of the central atom, and the desired energy in eV.
Note that the values returned depend on the data resource used. See the Xray::Absorption manpage.
This is called mcmaster for historical reasons. It calculates the normalization correcion for a given central atom.
$sigma_mm = &mcmaster($central, $edge);
It takes the central atoms tag and the alphanumeric edge symbol as arguments and returns the normalization correction in units of Angstrom squared.
Note that the values returned depend on the data resource used. See the Xray::Absorption manpage.
This calculates the correcion due to the I0 fill gases in a fluorescence experiment.
$sigma_i0 = &i_zero($central, $edge, $nitrogen, $argon, $krypton);
It takes the central atoms tag, the alphanumeric edge symbol, and the volume percentages of the three gases as arguments. It assumes that any remaining volume is filled with helium and it correctly accounts for the fact that nitrogen is a diatom. It returns the I0 correction in units of Angstrom squared.
Note that the values returned depend on the data resource used. See the Xray::Absorption manpage.
This calculates the correcion due to self-absorption fluorescence experiment. It assumes that the sample is infinately thick and that the entry and exit angles of the photons are the same.
$sigma_i0 = &self($central, $edge, \$cell);
It takes the central atoms tag, the alphanumeric edge symbol, and a reference to a populated cell. It returns a list whose zeroth element is the multiplicative amplitude correction and whose first element is the a correction in units of Angstrom squared.
Note that the values returned depend on the data resource used. See the Xray::Absorption manpage.
This exported routine builds a spherical cluster from a populated unit cell by constructing a rhomboid of an intger number of complete cells which fully encloses the sphere. The spherical cluster is probably not stoichiometric.
build_cluster(\$cell, \$keywords, \@cluster, \@neutral);
The first two arguments are (references to) cell and keywords objects. The cell should already have been populated by the populate method. The thrid argument is a reference to an array that will contain the cluster. The fourth argument is an unused placeholder.
The @cluster array is an anonymous array or arrays. Each entry in @cluster is an array containing x, y, z, r, r squared, x, y, z, the formula for x, the formula for y , and the formula for z. The first three arguments are the coordinates to full precision. The fourth through seventh arguments are of limited precision and are used internally for sorting the cluster.
This takes no arguments and returns the name of the Atoms runtime configuration file belonging to the user. This does the ``right thing'' on the different platforms.
This takes no argmuents and returns a list containing the values of variables (but not of fonts or colors) read from the rc file. They are in the following order:
$always_write_feff $atoms_language $write_to_pwd $prefer_feff_eight $absorption_tables $dafs_default $plotting_hook $default_filepath $display_balloons $no_crystal_warnings $one_frame $convolve_dafs $never_ask_to_save
New values will always be added to the end of the list to avoid beaking scripts that use this function.
This takes a text string and attempts to evaluate it as a number. It uses eval and so allows for simple math expressions, but it tries to be safe and not eval just any old math expression. You can use this if you want to evaluate numbers in the same manner as Atoms.
$x = number(1/3);
printf "%7.5f\n", $x;
|--> 0.33333
There is more information available in the Atoms document. There you will find complete descriptions of atp files, calculations using the Xray::Absorption package, keywords in atoms input files and lots of other topics.
Bruce Ravel <ravel@phys.washington.edu> Atoms URL: http://feff.phys.washington.edu/~ravel/software/atoms/
use Xray::Xtal;
my $cell = Xray::Xtal::Cell -> new(); $cell -> make( Space_group=>"f m -3 m", A=>3.961, );
my @sites; $sites[0] = Xray::Xtal::Site -> new(); $sites[0] -> make( X=>0.0, Y=>0.0, Z=>0.0, Element=>"Cu" );
$cell -> populate(\@sites); $cell -> verify_cell();
The preceding lines define a unit cell for FCC copper.
As suggested in the synopsis, these objects are closely related to one another. In fact, the method of translating a unique site to a set of symmetry-related sites requires a Cell object as an argument. Similarly, the method of populating a unit cell requires a list of Site objects as its argument. Consequently it is very unusual to use one of these classes and not the other.
In its current form, Xtal.pm is intended to solve simple crystallography problems of the sort commonly encountered by the X-ray absorption spectroscopist. Given a description of a crystal in terms of a space group symbol, axis lengths and angles, and the fractional coordinates of the unique crystallographic sites, Xtal.pm is used to describe the entire contents of the unit cell either in fractional or Cartesian coordinates.
To this end, two packages are included in Xtal.pm which define two data classes. One is a Cell and the other is a Site. Alone, Xtal.pm provides only these data classes. This, however, is the basis of several useful applications. The initial use of this module is to create lists of atomic coordinates of the sort needed for ball-and-stick figures or real-sapce multiple scattering calculations (which is the reason Xtal.pm was created). Xtal.pm can also be useful, for example, for powder diffraction or anomalous scattering simulations.
Xtal.pm obtains its crystallography data from a database which comes with the distribution. The space groups database is stored to disk using the Storable module with portable binary ordering. This choice allows both speed and networked applicability.
The following CPAN modules may not be part of a normal perl installation, but are needed by Xtal.pm:
Storable, File::Spec, Chemistry::Elements
A unit cell is constructed by new(); and the attributes of the unit cell are set using the make method. An example of the use of make to set the a lattice constant:
$cell -> new() -> make( A=4.0 );
The attributes of the Cell object are stored internally as capitalized words i.e. words that begin with an upper case letter and have lower case for the remaining letters, however the user is free to mix case in any convenient manner.
The Cell attributes that can be set using make are:
The bare minimum required to define is a cell is the a lattice constant and the space group symbol. All other attributes have sensible defaults or are calculated quantities. Of course, any space group of lower than cubic symmetry will require that other axes and/or angles be specified.
There are several other Cell attributes. Except for the Contents attribute, these are updated every time the make method is called. These include:
my ($contents) = $cell -> attributes("Contents");
foreach my $pos (@{$contents}) {
printf "x=%8.5f, y=%8.5f, z=%8.5f$/",
$$pos[0], $$pos[1], $$pos[2]
};
The x-x element of the metric tensor computed from the axes and angles. This is used to translate from fractional to cartesian coordinates.
The y-x element of the metric tensor computed from the axes and angles.
The y-z element of the metric tensor computed from the axes and angles.
The z-x element of the metric tensor computed from the axes and angles.
The z-z element of the metric tensor computed from the axes and angles.
Xray::Xtal::Cell will only allow you to directly modify the lattice constants and angles and the space group using the make method. While it is common for object definitions to allow the user to define new attributes, that is not allowed for a Cell object. There truly only are 8 attributes of a Cell which the user should allowed to set.
There are several other function that may be useful in your programs. Some of these are methods and some are non-exported functions. Except as noted, these subroutines are from the Xray::Xtal::Cell package.
$cell -> Xray::Xtal::Cell::new()
-> make("A"=>4.0, "B"=>4.3, "C"=>4.6)
($a, $b, $c) = $cell -> attributes("A", "B", "C");
$site -> Xray::Xtal::Site::new()
-> make("X"=>0.5, "Y"=>0.25, "Z"=>0)
($x, $y, $z) = $site -> attributes("X", "Y", "Z");
print "$x, $y, $z, $a, $b, $c$/";
|-> 0.5, 0.25, 0, 4.0, 4.3, 4.6
$cell -> clear();
$cell -> populate(\@sites)
This fills the Contents attribute of the Cell with an anonymous array. Each element of the anonymous array is itself an anonymous array whose first three elements are the x, y, and z fractional coordinates of the site and whose fourth element is a reference to the Site that generated the position. This is, admitedly, a complicated data structure and requires a lot of ``line-noise'' style perl to dereference all its elements. It is, however, fairly efficient.
$string = Xray::Xtal::Cell::canonicalize_symbol($string);
For example
Xray::Xtal::Cell::canonicalize_symbol('pm3m')
yields "P m -3 m"
$class = $cell -> crystal_class();
$cell -> verify_cell();
($x,$y,$z) = $cell -> metric($xf, $yf, $zf);
This method is called repeatedly by the build_cluster function in the Xray::Atoms module. The elements of the metric tenor, i.e. the Txx, Tyx, Tyz, Tzx, and Tz Cell attributes, are used to make the transformation according to this formula:
/ Txx 0 0 \ / xf \
(x y z) = | Tyx 1 Tyz | | yf |
\ Tzx 0 Tzz / \ zf /
$d = $cell -> d_spacing($h, $k, $l);
$p = $cell -> multiplicity($h, $k, $l);
See the footnote in Cullity page 523 for a caveat.
($elem_c, $x_c, $y_c, $z_c) = $cell -> central($central_tag)
In many cases there is more than one choice for the central atom. Any of the various crystallographically identical positions matching the tag of the central atom can be chosen. This method returns the one closest to the center of the unit cell, i.e. the one closest to (1/2,1/2,1/2). The meaning of the word "closest" is a bit strange in this context. It is the position with the smallest value of
sqrt( (x-0.5)**2 + (y-0.5)**2 + (z-0.5)**2 )
This is chosen for speed and efficiency in building a spherical cluster of atoms.
@overfull = $cell -> overfull($epsi);
Each element of @overfull is an anonymous array containing the x, y, and z fractional coordinates and a reference to the Site that generated the position.
print $cell -> warn_shift;
print $cell -> cell_check;
$positions = $cell -> get_symmetry_table;
@first_position = @ {$positions[0]};
The Site object is a blessed hash. It predefines several attributes of a Site, but allows the user to define new attributes on the fly. The predefined (i.e. the ones that are used in Atoms) attributes are:
A character string identifying a unique crystallographic site.
A pseudo-random number assigned by the new method to uniquely identify the object.
See the descriptions of attributes and clear in the Cell Package section.
$site -> clear();
$site -> clear(\$cell);
Typically, it is not necessary to call this explicitly as it is called for each site by the Cell populate method.
$coord = Xray::Xtal::Site::canonicalize_coordniate($coord);
You may specify space group symbols in a variety of ways. When presented with a possible symbol, the Xtal module will first clean the symbol up by adding and/or removing whitespace then by trying each of the following ways of interpreting the symbol.
Since whitespace in the symbol is regularized, you can usually include or omit whitespace in any fashion. For example pm3m and P m -3 m both come out as P m -3 m, just as you would expect.
A space group is specified using the make method from the Cell class. When this is done the original symbol is stored in the Given_
There is a more complete discussion of low symmetry groups in the Atoms document. Here are the highlights:
Monoclinic groups can be quite confusing for the user. Because any of the three angles can be the unique (acute or obtuse rather than right) angle and because there are three possible settings for the cell, the standard symbol can be ambiguous. In that case, using the full symbol or the short monoclinic symbol would break the ambiguity and allow the make method to correctly assign the space group. An example would help illustrate this.
In "Structural phase diagram of La(1-x)Sr(x)MnO(3+delta): Relationship to magnetic and transport properties." by J.F. Mitchell et al, Phys. Rev. B54, no. 9, (1996), pp./ 6172-6183 the monoclinic structure for room temperature LnMnO3 is given in Table IV. The space group is given as P 21/c and the setting is given as P 1 21/n 1. Specifying the space group symbol will result in the wrong application of symmetries when the Contents attribute of the cell is filled. Specifying the full symbol for that setting will work correctly. The shorthand P 21/n will also result in a correct applciation of symmetries.
In the Atoms document, there is a complete list of symbols recognized by Atoms, including all the short and full symbols for the different settings of monoclinic groups. It is essential to always use site coordinates and unique angles appropriate to the symbol (and vice versa).
In the strange case of crystal data in a monoclinic setting but with the unique angle equal to 90, it is necessary to specify the unique angle like so
$cell -> make(Angle=>'beta')
Without this, there is no way for the Cell class to know which setting to use.
You may use any setting of an orthorhombic crystal, although it is up to you to be sure that the unique coordinates are appropriate to that setting. Atoms has no way of checking that!
F and C centered tetragonal cells are handled transparently by Atoms. If you find a literature reference using one of these, you can usually use the crystal data given in the article as written.
You can specify either hexagonal or rhombohedral parameters for rhombohedral space groups. For the hexagonal representation, you must specify a and b and c, alpha, beta, and gamma will be set correctly by the make method. For the rhombohedral representation, you must specify a and alpha and the rest will be set appropriately.
Bruce Ravel <bruce@phys.washington.edu> http://feff.phys.washington.edu/~ravel/software/
use Tk;
use Xray::Xtal;
use Xray::Tk::SGB;
$browser = $top -> SGB(-SpaceWidget=>\$space_field);
$browser -> configure(@sgb_args);
$browser -> Show;
Configuration parameters are described below.
The only non-standard method is Show, which is used to actually display the browser on your screen. Show always returns 0;
Other properties, such as -foreground are inherited and may be configured.
All of the text displayed in the SGB widget can be customized using configure. The primary purpose of this is to allow the use of other languages in the SGB widget. The following list shows the configure switch and its default value. You should play around with SGB before translating or otherwise changing them so you can see what each string is used for.
Dismiss
Back
Restore
Triclinic
Monoclinic
Orthorhombic
Tetragonal
Trigonal
Hexagonal
Cubic
Mouse-1 to insert this symbol.
Mouse-1 to display space group
Any mouse button for groups of this class.
Restore the initial symbol:
Dismiss the space group browser.
groups
Mouse-1=insert Mouse-3=describe
Return to the previous screen.
Number
Space group index from ITC
Schoenflies
Schoenflies notation
Full symbol
Symbol denoting complete symmetries
New symbol
Symbol using \"e\" for the glide plane
1935 symbol
Symbol from the 1935 edition of ITXC
Shorthand
Special strings recognized by Atoms
Settings
Symbols for alternate settings
Short symbols
Short symbols for alternate settings
Select a crystal class to display all space groups within that class.
View current group:
Space group listing:
Various symbols which may be used to describe space group:
Note:
The first three settings are for the b axis and beta angle unique. The next three are for the c axis and gamma angle unique. The final three are for the a axis and alpha angle unique. Within each group, the three choices are the possible choices of axes. Atoms has no a priori way of knowing the correct setting for your data.
The five additional settings correspond to the five additional ways of setting a coordinate system in 3-space. They correspond to permutations of ba-c, cab, -cba, bca, and a-cb away from the standard setting, abc. Atoms has no a priori way of knowing the correct setting for your data.
C and F centered tetragonal cells are related to the standard cells by a 45 degree rotation in ab plane and a doubling of the cell volume. Atoms has no a priori way of knowing the correct setting for your data.
You may use the rhombohedral parameters, in which case you must specify a and alpha. You may also use the trigonal parameters in which case you must specify a and c. The trigonal representation has three times the volume of the rhombohedral representation. Atoms has no a priori way of knowing the correct setting for your data.
Use of the browser is pretty straight forward because the status bar at the bottom of the widget always informs the user about what actions are available.
The opening panel displays the seven crystal classes. The names of the crystal classes are active text. Clicking any mouse button on a crystal class will display a list of all space groups in that class. If the widget specified by -SpaceWidget is displaying a valid group symbol, then that symbol will be displayed as active text. Clicking Mouse-1 one on that symbol will jump to the panel describing that symbol.
The second panel displays lists of space groups divided by crystal class. The index of the group (as indexed in the International Tables of Crystallography) and the canonical (Hermann-Maguin) space group symbol are shown. The space group symbols are active text. Clicking Mouse-1 will insert that symbol into the widget given by -SpaceWidget. Clicking Mouse-3 will display information about that group.
The last panel is the space group description. It shows all symbols recognized as describing that group by the database in Xray::Xtal, which is use-ed by Xray::Tk::SGB. Clicking Mouse-1 on any active text will insert that symbol into the widget given by -SpaceWidget.
At the bottom of the widget are three buttons. The back button causes the previous panel to be displayed. The restore is only active if the widget given by -SpaceWidget contains a symbol. If so, pressing it will restore that widget to its initial value. The dismiss button destroys the SGB widget.
Bruce Ravel <ravel@phys.washington.edu> (c) 1999 http://feff.phys.washington.edu/~ravel/software/ http://feff.phys.washington.edu/~ravel/software/atoms/
This code is distributed with Atoms and may be redistributed under the same terms as Atoms, which are the same terms as Perl itself.
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.
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.
$this = Xray::Absorption -> current_resource;
Identifies the currently selected resource.
$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.
$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 = 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.
$xsec = Xray::Absorption -> cross_section($elem, $edge, $mode);
Return the cross section in barns/atom of $elem at $energy. 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.
$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.
@list = Xray::Absorption -> available;
Returns a list of all available data resource.
@list = Xray::Absorption -> scattering;
Returns a list of all available data resource which contain anomalous scattering functions.
@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.
$value = Xray::Absorption -> get_atomic_weight($elem);
Return the atomic weight of $elem.
$value = Xray::Absorption -> get_density($elem);
Return the specific gravity of the pure material of $elem.
$value = Xray::Absorption -> get_conversion($elem);
Return the factor for converting between barns/atom and cm squared/gram for $elem.
$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.
$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.
$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.
$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.
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.
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.
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).
Bruce Ravel <ravel@phys.washington.edu> http://feff.phys.washington.edu/~ravel/software/Xray/Absorption/
use Xray::Absorption;
Xray::Absorption -> load("mcmaster");
See the documentation for Xray::Absorption for details.
The data in this module, commonly referred to as "The McMaster Tables", was originally published as
Compilation of X-Ray Cross Sections W.H. McMster, N. Kerr Del Grande, J.H. Mallett, J.H. Hubbell National Bureau of Standards UCRL-50174 Section II Revision 1 (1969) Available from National Technical Information Services L-3 United States Department of Commerce
The data is contained in a database file called mcmaster.db which is generated at install time from a flat text database of the McMster data. The data originally comes from mucal.f, a Fortran subroutine originally written by Dr. Pathikrit Bandhyapodhyay.
The required Chemistry::Elements module is available from CPAN in the miscellaneous modules section.
The McMaster data resource only includes K and L 1-3 edges. For light elements, it provides only a single L edge energy -- that for the L1 edge. For heavier elements it provides a single M energy, the energy of the M1 edge. It only supplies four generic fluorescence line energies, Kalpha, Kbeta, Lalpha, and Lbeta. In each case the energy provided is the energy of the brightest line of that sort.
Bruce Ravel, bruce@phys.washington.edu http://feff.phys.washington.edu/~ravel/software/Absorption/
use Xray::Absorption;
Xray::Absorption -> load("elam");
See the documentation for Xray::Absorption for details.
The data in this module, here referred to as "The Elam Tables", will be published real soon. The compilation of data is the work of Tim Elam (tim.elam@nrl.navy.mil).
The data is contained in a database file called elam.db which is generated at install time from a flat text database of the Elam data. The data is stored in a Storable archive using "network" ordering. This allows speedy disk and memory access along with network and platform portability.
The required Chemistry::Elements, Math::Spline, and Math::Derivative modules are available from CPAN.
K-shell fluorescence yield below Z=11 from new fits in J. H. Hubbell et. al., J. Chem. Phys. Ref. Data, Vol. 23, No. 2, 1994, pp. 339-364.
Fluorescence yields and Coster-Kronig transition rates for K and L shells Krause, J. Phys. Chem. Ref. Data, Vol. 8, No. 2, 1979, pp. 307-327. values for wK, wL2,and f23 are from Table 1. (values for light atoms in condensed matter) (note that this produces a large step in f23 values at z=30, see discussion in reference section 5.3 L2 Subshell and section 7 last paragraph)
Values of wL1 for Z=85-110 and f12 for Z=72-96 from Krause were modified as suggested by W. Jitschin, "Progress in Measurements of L-Subshell Fluorescence, Coster-Kronig, and Auger Values", AIP Conference Proceedings 215, X-ray and Inner-Shell Processes, Knocxville, TN, 1990. T. A. Carlson, M. O. Krause, and S. T. Manson, Eds. (American Institute of Physics, 1990).
Fluorescence yields and Coster-Kronig transition rates for M shells Eugene J. McGuire, "Atomic M-Shell Coster-Kronig, Auger, and Radiative Rates, and Fluorescence Yields for Ca-Th", Physical Review A, Vol. 5, No. 3, March 1972, pp. 1043-1047.
Fluorescence yields and Coster-Kronig transition rates for N shells Eugene J. McGuire, "Atomic N-shell Coster-Kronig, Auger, and Radiative Rates and Fluorescence Yields for 38 <= Z <= 103", Physical Review A 9, No. 5, May 1974, pp. 1840-1851. Values for Z=38 to 50 were adjusted according to instructions on page 1845, at the end of Section IV.a., and the last sentence of the conclusions.
Relative emission rates, fits to low-order polynomials, low-Z extrapolations by hand and eye data from Salem, Panossian, and Krause, Atomic Data and Nuclear Data Tables Vol. 14 No.2 August 1974, pp. 92-109. M shell data is from T. P. Schreiber and A. M. Wims, X-ray Spectrometry Vol. 11, No. 2, 1982, pp. 42-45. Small, arbitrary intensities assigned to Mgamma and Mzeta lines.
Cross sections are in cm2/gm vs energy in eV. Berger and Hubbell above 1 keV, Plechaty et. al. below.
Reference: M. J. Berger and J. H. Hubbell, XCOM: Photon Cross Sections on a Personal Computer, Publication NBSIR 87-3597, National Bureau of Standards, Gaithersburg, MD, 1987. Machine-readable data from J. H. Hubbell, personal communication, Nov. 9, 1998. The data were updated as of May 7, 1998 (XCOM Version 2.1).
Reference: Plechaty, E. F., Cullen, D. E., and Howerton,R.J, "Tables and Graphs of Photon Interaction Cross Sections from 0.1 keV to 100 MeV Derived from the LLL Evaluated Nuclear Data Library," Report UCRL-50400, Vol. 6, Rev. 3, NTIS DE82-004819, Lawrence Livermore National Laboratory, Livermore, CA. (1981). Machine-readable data from D. B. Brown, Naval Research Laboratory.
The behaviour of the get_energy method in this module is a bit different from other modules used by Xray::Absorption. This section describes methods which behave differently for this data resource and methods offered by this module which are not available for other resources.
$energy = Xray::Absorption -> get_energy($elem, $edge)
This behaves similarly to the get_energy method of othe resources, except there are some differences regarding the syntax of specifying $edge. When using the Elam data resource, $edge can be any of K, L1-L3, M1-M5, N1-N7, O1-O7, or P1-P3. To get a fluorescence line, you may use any Siegbahn or IUPAC symbol to specify the line. See the pod in Xray::Absorption for details about these symbols. You may also specify a "generic" Siegbahn symbol, such as Kalpha. The energy that is returned depends on the value of an internal variable which may be set using the line_toggle method. If the toggle is set to "brightest", the energy of the brightest line of the class is returned. In the case of "Kalpha", the energy or the Kalpha1 line is returned. If the toggle is set to "weighted" then the intestity weighted average energy of all lines of the class is returned. "weighted" is the default.
$energy = Xray::Absorption -> line_toggle("brightest");
$energy = Xray::Absorption -> get_energy("cu", "kalpha");
$energy = Xray::Absorption -> line_toggle("wieghted");
$energy = Xray::Absorption -> get_energy("cu", "kalpha");
When "weighted" is selected, this returns the intensity weighted energy of the various Kalpha lines. When "brightest" is chosen, this returns the energy of the Kalpha1 line because that is the brightest Kalpha line. The default is "weighted". Case does not matter for the argument, but spelling does. If the argument is not spelled correctly then the calculation method is not toggled.
$intensity = Xray::Absorption -> get_intesity($elem, $symbol)
Get the relative of the line specified by $symbol for the element $elem. $elem can be a two letter symbol, a full name, or a Z number. $symbol may be either a Siegbahn or IUPAC symbol. The intesities are such that all lines of a type (e.g. all Kalpha lines) have intesities which sum to 1. If $elem or $symbol is not recognized, then this returns 0.
The Elam data resource provides a fairly complete set of edge and line energies. Any edge tabulated on the Gwyn William's Table of Electron Binding Energies for the Elements (that's the one published by NSLS and on the door of just about every hutch at NSLS) is in the Elam data resource. Additionally, a large but not exhaustive collection of line energies is tabulated. Every line in the table in the SYMBOLS FOR FLUORESCENCE LINES section of the Absorption.pm pod is included in the Elam tables. A reasonable value for the relative line intensity if also included in this table. See (the elam reference) for a discussion of which lines were included in the tables and how the intensities were calculated.
Bruce Ravel, bruce@phys.washington.edu http://feff.phys.washington.edu/~ravel/software/Absorption/
use Xray::Absorption;
Xray::Absorption -> load("henke");
See the documentation for Xray::Absorption for details.
The data in this module, referred to as "The Henke Tables", was published as
B. L. Henke, E. M. Gullikson, and J. C. Davis, Atomic Data and Nuclear Data Tables Vol. 54 No. 2 (July 1993).
The Henke data is available on the web at http://www-cxro.lbl.gov/optical_
The behaviour of the methods in this module is a bit different from other modules used by Xray::Absorption. This section describes methods which behave differently for this data resource.
$energy = Xray::Absorption -> get_energy($elem, $edge);
This behaves similarly to the get_energy method of the other resources. When using the Henke data resource, $edge can be any of K, L1-L3, M1-M5, N1-N7, O1-O7, or P1-P3. Line energies are not supplied with the Henke data set. The line energies from the McMaster tables are used.
$xsec = Xray::Absorption -> cross_section($elem, $energy, $mode);
This behaves slightly differently from the similar method for the McMaster and Elam resources. The Henke tables are actually tables of anomalous scattering factors and do not come with coherent and incoherent scattering cross-sections. The photo-electric cross-section is calculated from the imaginary part of the anomalous scattering by the formula
mu = 2 * r_e * lambda * conv * f_2
where, r_e is the classical electron radius, lamdba is the photon wavelength, and conv is a units conversion factor.
r_e = 2.817938 x 10^-15 m
lambda = 2 pi hbar c / energy
hbar*c = 1973.27053324 eV*Angstrom
conv = Avagadro / atomic weight
= 6.022045e7 / weight in cgs
The $mode argument is different here than for the other resources. The options are "xsec", "f1", and "f2", telling this method to return the cross-section or the real or imaginary anomalous scattering factor, respectively.
The values for f1 and f2 are computed by linear interpolation of a semi-log scale. Care is taken to avoid the discontinuities at the edges.
Because the Henke tables do not include the coherent and incoherent scattering terms, the value returned by get_energy may be a bit smaller using the Henke tables than that from the McMaster tables.
The Henke data resource provides a fairly complete set of edge energies. Any edge tabulated on the Gwyn William's Table of Electron Binding Energies for the Elements (that's the one published by NSLS and on the door of just about every hutch at NSLS) is in the Henke data resource. The Henke data comes with the same, limited set of fluorescence energies as McMaster.
Bruce Ravel, bruce@phys.washington.edu http://feff.phys.washington.edu/~ravel/
use Xray::Absorption;
Xray::Absorption -> load("chantler");
See the documentation for Xray::Absorption for details.
The data in this module, referred to as "The Chantler Tables", was published as
C. T. Chantler
Theoretical Form Factor, Attenuation, and Scattering Tabulation
for Z = 1 - 92 from E = 1 - 10 eV to E = 0.4 - 1.0 MeV
J. Phys. Chem. Ref. Data 24, 71 (1995)
This can be found on the web at
http://physics.nist.gov/PhysRefData/FFast/Text/cover.html
The Chantler data is available on the web at
http://physics.nist.gov/PhysRefData/FFast/html/form.html
More information can be found on the personal web page of C.T. Chantler
http://optics.ph.unimelb.edu.au/~chantler/home.html
The data contained in a database file called chantler.db which is generated at install time from the flat text files of the Chantler data. The data is stored in a Storable archive using "network" ordering. This allows speedy disk and memory access along with network and platform portability.
The required File::Spec, Chemistry::Elements, and Storable modules are available from CPAN.
The behaviour of the methods in this module is a bit different from other modules used by Xray::Absorption. This section describes methods which behave differently for this data resource.
$energy = Xray::Absorption -> get_energy($elem, $edge);
This behaves similarly to the get_energy method of the other resources. When using the Chantler data resource, $edge can be any of K, L1-L3, M1-M5, N1-N7, O1-O5, or P1-P3. Line energies are not supplied with the Chantler data set. The line energies from the McMaster tables are used.
$xsec = Xray::Absorption -> cross_section($elem, $energy, $mode);
This behaves slightly differently from the similar method for the McMaster and Elam resources. The Chantler tables contain anomalous scattering factors and the sum of the coherent and incoherent scattering cross-sections. The photo-electric cross-section is calculated from the imaginary part of the anomalous scattering by the formula
mu = 2 * r_e * lambda * conv * f_2
where, r_e is the classical electron radius, lamdba is the photon wavelength, and conv is a units conversion factor.
r_e = 2.817938 x 10^-15 m
lambda = 2 pi hbar c / energy
hbar*c = 1973.27053324 eV*Angstrom
conv = Avagadro / atomic weight
= 6.022045e7 / weight in cgs
The $mode argument is different here than for the other resources. The options are "xsec", "f1", "f2", "photo", and "scatter" telling this method to return the full cross-section cross-section, the real or imaginary anomalous scattering factor, just the photoelectric crosss-section, or just the coherent and incoherent scattering, respectively.
The values for f1 and f2 are computed by linear interpolation of a semi-log scale, as described in the literature reference. Care is taken to avoid the discontinuities at the edges.
The Chantler data resource provides a fairly complete set of edge energies. Any edge tabulated on the Gwyn William's Table of Electron Binding Energies for the Elements (that's the one published by NSLS and on the door of just about every hutch at NSLS) is in the Chantler data resource. The Chantler data comes with the same, limited set of fluorescence energies as McMaster.
Bruce Ravel, bruce@phys.washington.edu http://feff.phys.washington.edu/~ravel/software/Absorption
use Xray::Absorption;
Xray::Absorption -> load("cl");
See the documentation for Xray::Absorption for details.
The data in this module and the Fortran code which it calls as a shared library, referred to as "The CL Tables", was published as
S. Brennan and P.L. Cowen, Rev. Sci. Instrum, vol 63, p.850 (1992)
More information about these data is available on the Web at
http://www.slac.ssrl.stanford.edu/absorb.html.
The values for the anomalous scattering factors are calculated using subroutines written in Fortran, wrapped in a swig wrapper and accessed using the Perl DynaLoader module.
The values of edge and line energies are contained in a database file called cl.db which is generated at install time from the flat text files of the these data. The data is stored in a Storable archive using "network" ordering. This allows speedy disk and memory access along with network and platform portability.
The required File::Spec, Chemistry::Elements, Storable are available from CPAN.
The behaviour of the methods in this module is a bit different from other modules used by Xray::Absorption. This section describes methods which behave differently for this data resource.
$energy = Xray::Absorption -> get_energy($elem, $edge);
This behaves similarly to the get_energy method of the other resources. When using the CL data resource, $edge can be any of K, L1-L3, M1-M5, N1-N7, O1-O7, or P1-P3. Line energies are not supplied with the CL data set. The line energies from the McMaster tables are used.
$xsec = Xray::Absorption -> cross_section($elem, $edge, $mode);
This behaves slightly differently from the similar method for the McMaster and Elam resources. The CL tables are actually tables of anomalous scattering factors and do not come with coherent and incoherent scattering cross-sections. The photo-electric cross-section is calculated from the imaginary part of the anomalous scattering by the formula
mu = 2 * r_e * lambda * conv * f_2
where, r_e is the classical electron radius, lamdba is the photon wavelength, and conv is a units conversion factor.
r_e = 2.817938 x 10^-15 m
lambda = 2 pi hbar c / energy
hbar*c = 1973.27053324 eV*Angstrom
conv = Avagadro / atomic weight
= 6.022045e7 / weight in cgs
The $mode argument is different here than for the other resources. The options are "xsec", "f1", and "f2", telling this method to return the cross-section or the real or imaginary anomalous scattering factor, respectively.
The values for f1 and f2 are computed by linear interpolation of a semi-log scale. Care is taken to avoid the discontinuities at the edges.
Because the CL tables do not include the coherent and incoherent scattering terms, the value returned by get_energy is a bit smaller using the CL tables than using the others.
The CL data resource provides a fairly complete set of edge energies. Any edge tabulated on the Gwyn William's Table of Electron Binding Energies for the Elements (that's the one published by NSLS and on the door of just about every hutch at NSLS) is in the CL data resource. The CL data comes with the same, limited set of fluorescence energies as McMaster.
Bruce Ravel, bruce@phys.washington.edu http://feff.phys.washington.edu/~ravel/software/Absorption
use Xray::Absorption::CLdata qw(fprime);
my $e_ref = [8000, 8500, 8900, 8950, 8970, 8990, 9000, 9200];
my $atom = 29;
fprime($atom, $e_ref, $f1, $f2);
for ($i = 0; $i<= $#{$e_ref}; $i++) {
print " $e_ref->[$i] $f1->[$i] $f2->[$i]\n";
}
use Xray::Absorption::CLdata qw(cl_f1 cl_f2); print " cl_f1(29,8000) = ". cl_f1(29,8000)."\n"; print " cl_f2(30,9500) = ". cl_f2(30,9500)."\n"; print " cl_f2(30,9700) = ". cl_f2(30,9700)."\n";
The fprime function provides the main interface to the Cromer-Liberman data. The call syntax is:
fprime($atom, $e_ref, $f1_ref, $f2_ref);
$atom is the atomic number of the element of interest and $e_ is an array reference to a list of energies, both of which are inputs to fprime. The output parameters $f1_ and $f2_ are references to arrays of f'(E) and f''(E) at each of the energy values specified.
This returns a single value of f'(E) for a given Z and energy. The syntax is
$f1 = cl_f1($Z, $energy);,
where $energy is a scalar value.
This returns a single value of f'' for a given Z and energy. The syntax is
$f2 = cl_f2($Z, $energy);.
where $energy is a scalar value.
use Xray::CromerMann qw(get_f get_valence in_CromerMann); $fnot = get_f($symb, $d);
4
f0 = sum [ ai*exp(-bi*s^2) ] + c
i=1
Thus there are 9 coefficients for each of the 213 tabulated element/valence symbols.
s is sin(theta)/lambda. (lambda*s)/2pi is the momentum transfer. s is simply related to the crystal d-spacing by s=1/2d.
The data for these tables can be found in Volume C of the International Tables of Crystallography, ed. A.J.C. Wilson, published by IUCr and Kluwer Academic Publishers (1992). The table starts on page 500 and a discussion can be found on page 487.
These tables are known to be inaccurate, particularly at high angles. This module is a toy. It is suitable for a student or for the sort of quick-n-dirty crystallographic hackery that the author indulges in.
$symb = "Ce3+"; $fnot = get_f($symb, $d);
If the symbol cannot be found in the table, get_f returns 0. It also returns 0 when $symbol consists of whitespace or is "null" or "nu". If $symbol is a number or the name of an element, then it assumes you want the Thomson scattering for the neutral element. The absolute value of $d_spacing is used by this function.
$symbol = get_valence($elem, $valence)
The function takes the nearest integer to $valence and uses that with the element symbol to construct the element/valence symbol. See the section on ELEMENTS AND VALENCE STATES.
@coefs = get_CromerMann_coefficients($elem)
$symb = "Ce3+"; $is_available = in_CromerMann($symb);
The following is a list of symbols for the tabulated elements and valence states. The final two are ways of refering to an empty site (i.e. a null or blank atom).
H H. H1- He Li Li1+ Be
Be2+ B C C. N O O1-
F F1- Ne Na Na1+ Mg Mg2+
Al Al3+ Si Si. Si4+ S P
Cl Cl1- Ar K K1+ Ca Ca2+
Sc Sc3+ Ti Ti2+ Ti3+ Ti4+ V
V2+ V3+ V5+ Cr Cr2+ Cr3+ Mn
Mn2+ Mn3+ Mn4+ Fe Fe2+ Fe3+ Co
Co2+ Co3+ Ni Ni2+ Ni3+ Cu Cu1+
Cu2+ Zn Zn2+ Ga Ga3+ Ge Ge4+
As Se Br Br1- Kr Rb Rb1+
Sr Sr2+ Y Y3+ Zr Zr4+ Nb
Nb3+ Nb5+ Mo Mo3+ Mo5+ Mo6+ Tc
Ru Ru3+ Ru4+ Rh Rh3+ Rh4+ Pd
Pd2+ Pd4+ Ag Ag1+ Ag2+ Cd Cd2+
In In3+ Sn Sn2+ Sn4+ Sb Sb3+
Sb5+ Te I I1- Xe Cs Cs1+
Ba Ba2+ La La3+ Ce Ce3+ Ce4+
Pr Pr3+ Pr4+ Nd Nd3+ Pm Pm3+
Sm Sm3+ Eu Eu2+ Eu3+ Gd Gd3+
Tb Tb3+ Dy Dy3+ Ho Ho3+ Er
Er3+ Tm Tm3+ Yb Yb2+ Yb3+ Lu
Lu3+ Hf Hf4+ Ta Ta5+ W W6+
Re Os Os4+ Ir Ir3+ Ir4+ Pt
Pt2+ Pt4+ Au Au1+ Au3+ Hg Hg1+
Hg2+ Tl Tl1+ Tl3+ Pb Pb2+ Pb4+
Bi Bi3+ Bi5+ Po At Rn Fr
Ra Ra2+ Ac Ac3+ Th Th4+ Pa
U U3+ U4+ U6+ Np Np3+ Np4+
Np6+ Pu Pu3+ Pu4+ Pu6+ Am Cm
Bk Cf O2-. ' ' Nu
Bruce Ravel, bruce@phys.washington.edu http://feff.phys.washington.edu/~ravel/software/