NAME

Demeter::Atoms - Convert crystallographic data to atomic lists

VERSION

This documentation refers to Demeter version 0.9.26.

SYNOPSIS

These lines behave much like any other version of Atoms:

  use Demeter;
  my $atoms = Demeter::Atoms -> new()
    -> read_inp($ARGV[0]||"atoms.inp")
      -> Write('feff6');

DESCRIPTION

This module implements Atoms in the Demeter system. The purpose of Atoms is to convert crystallographic data into a list of atomic coordinates of the sort used by Feff as input data. This greatly simplifies the chore of making Feff input files for crystalline materials.

ATTRIBUTES

The following are the attributes of the Data object. Attempting to access an attribute not on this list will throw an exception.

The type of argument expected in given in parentheses. i.e. number, integer, string, and so on. The default value, if one exists, is given in square brackets.

Input parameters

space (string): The space group ofthe crystal. This can be in any form recognized by Xray::Crystal::Cell, including Hermann-Maguin, Schoenflies, number, or one of a few nicknames.
a (real): The length of the A lattice constant in Angstroms.
b (real): The length of the B lattice constant in Angstroms.
c (real): The length of the C lattice constant in Angstroms.
alpha (real): The angle between B and C, in degrees.
beta (real): The angle between A and C, in degrees.
gamma (real): The angle between A and B, in degrees.
rmax (real): The extent of the cluster generated from the input crystal data.
rpath (real): The value used for the RMAX keyword in the feff.inp file. This is the length of the longest path to be calculated by the pathfinder. A value much larger than about 6 will bog down Demeter's pathfinder in its current form.
edge (string) [k or l3 depending on Z-number]: The edge of the absorber.
core (string) [first sitin the list]: The identifier of the absorber. This should be one of the site tags.
shiftvec (vector) [0,0,0]: The value of the shift vector, should one be necessary.
file (filename): The name of an atoms input file.
cif (filename): The name of a CIF file.
record (string) [0]: The record to import from a multi-record CIF file. The default is to read the first record. Note that this is zero-based while you user interface probably should be one-based.
titles (array of strings): An array of strings containing the title lines read from the input data.
template (output template) [feff6]: The output template.
ipot_style (string) [elements]: The style for generating the potentials list in a Feff input file. The choices are sites, elements, and tags.

Progress flags

is_imported (boolean) [false]: This is set to true when data is imported from a file.
is_populated (boolean) [false]: This is set to true when the cell is populated.
is_expanded (boolean) [false]: This is set to true when the populated cell is expanded into a cluster.
is_ipots_set (boolean) [false]: This is set to true when the unique potentials are assigned.
partial_occupancy: This is set to true if the input crystal data includes sites with partial occupancy.

Crystallography

sites (list of Site objects)

This is a reference to the array of Site objects in the cluster.

cell (reference to Cell object)

This is a reference to the Cell object associated with this Atoms object.

cluster (list)

This is a list containing the expanded cluster. Need to describe each list entry.

is_rhomb, is_hex, is_first, is_second (boolean)

Occassionally, modifiers to the space group symbol are used to explicitly specify the setting of the crystal.

Trigonal space groups with symbols beginning with R (numbers 146, 148, 155, 160, 161, 166, and 167) can be expressed in rhombohedral or hexagonal settings. While it is possible to figure out the setting from the specified parameters -- the rhombohedral setting has a=b=c, alpha!=90, and alpha=beta=gamma, while the hexagonal setting has a=b!=c, alpha=beta=90, and gamma=120 -- CIF file authors and others may modify the space group symbol with :R or :H to indicated the setting.

Some orthoganal groups (numbers 48, 50, 59, 68, 70), tetragonal groups (85, 86, 88, 125, 126, 129, 130, 133, 134, 137, 138, 141, 142), and cubic groups (201, 203, 222, 224, 227, 228) are given in the International Tables referenced to two centers of symmetry. In general, it is difficult to know which center is used before expanding the unit cell and examining its contents. To remove this ambiguity some CIF file authors and others will modify the space group symbol with :1 or :2 to indicated which center has been used. Demeter assumes the second setting, so if :1 is specified, it is likely that a shift vector will be needed.

When a space group symbol uses one of these modifiers, the corresponding boolean parameter will be set to 1.

METHODS

Various methods for populating the cell, explanding the cluster, and other chores are not documented here. These things will happen as needed when any of the output generating methods are called.

Accessor methods

set

Set attributes. This takes a single argument which is a reference to a hash of attribute values. The keys of that hash are any of the valid object attributes listed above.

  $atoms -> set(a => 3.81, rmax => 6);

get

Retrieve attribute values. This works in scalar and list context.

  $a = $atoms -> get("a");
  @cell_constants = $atoms -> get(qw(a b c alpha beta gamma));

Main methods

read_inp

Import crystal data from an Atoms input file.

  $atoms -> read_inp("atoms.inp");

read_cif

Import crystal data from a CIF file.

  $atoms -> read_cif("your_data.cif");

See Demeter::Atoms::Cif for more details.

atoms_file

Generate text suitable for an atoms input file.

  print $atoms -> atoms_file;

Write

Write out an output file using a specified output template.

  print $atoms->Write($template);

Several types are already defined, see "TEMPLATES".

Methods for doing absorption calculations

xsec: Return the length in microns of the sample required for a total absorption length of 1.
deltamu: Return the length in microns of the sample required for an edge step of 1.
density: Return the density as a unitless specific gravity. The density os computed from the unit cell volume and the mass of the contents of the cell.
mcmaster: Return an approximation of the effect of unit normalization on the sigma^2 values measured in an EXAFS analysis.
i0: Return an approximation of the effect of the energy response of the I0 detector on the sigma^2 values in a fluorescence EXAFS measurement.
selfsig: Return an approximation of the effect of self-absorption on the sigma^2 values in a fluorescence EXAFS measurement.
selfamp: Return an approximation of the effect of self-absorption on the amplitude in a fluorescence EXAFS measurement.
netsig: Return the sum of the three sigma^2 corrections.

TEMPLATES

Atoms templates use the syntax of Text::Template. This is a simple templating language which has snippets of perl code interspersed among plain text.

atoms: An input file for atoms. Calling the Write method with atoms as the argument is identical to calling the atoms_file method.
p1: The entrie contents of the fully decorated unit cell, written as an input file for atoms using the P1 space group.
feff6: An input file for feff6.
feff7: An input file for feff7.
feff8: An input file for feff8.
absorption: Text with the results of various caluclations using tables of xray absorption coefficients.
spacegroup: A brief description of the space group, including alternate symbols and a list of equivalent positions.

New output types can be defined by writing new template files. Any template files found on your system can be used as the argument to the Write method.

DIAGNOSTICS

Atoms: \"$file\" does not exist": Your atoms input file or CIF file could not be found.
Atoms: \"$file\" could not be read": Your atoms input file or CIF file could not be read,probably due to a permissions problem.
Unknown Atoms template file -- type $file: $tmpl": The template file specified in the call to the Write method could not located.
"$key" is not a valid Demeter::Atoms parameter: You have attempted to set an unrecognized keyword.
You have $i unique potentials, but Feff only allows 7.: Your choice of ipot style has resulted in more than 7 unique potentials being defined. Feff will refuse to run with that many.
"$key" is a deprecated Atoms keyword ($file line $.): While reading an Atoms input file, you have come across a keyword that was recognized in an earlier version of Atoms, but which is no longer supported. It's value was ignored.
"$key" is not an Atoms keyword ($file line $.): While reading an Atoms input file, you have come across a keyword that is not an Atoms keyword. It's value was ignored.

SERIALIZATION AND DESERIALIZATION

The atoms input file is used for serialization of input data. Output data should be associated with a Feff object and serialization of the output should be handled as a Feff object.

CONFIGURATION AND ENVIRONMENT

See Demeter::Config for a description of the configuration system. Atoms uses the atoms configuration group.

DEPENDENCIES

The dependencies of the Demeter system are in the Build.PL file.

BUGS AND LIMITATIONS

Need to implement a feff.inp parser for OpenBabel to enable a much broader range of output formats.
Neutral (parallelipiped) cluster?
Need overfull, p1_cartesian, gnxas outout.
Location in user space for user-defined templates.
Need more testing of spacegroups and database.

Please report problems to the Ifeffit Mailing List (http://cars9.uchicago.edu/mailman/listinfo/ifeffit/)

Patches are welcome.

AUTHOR

Bruce Ravel, http://bruceravel.github.io/home

http://bruceravel.github.io/demeter

LICENCE AND COPYRIGHT

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

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.