ATOMS has no hard-wired output types. All output from ATOMS is controlled using files called ATOMS template files, or atp files. ATOMS comes with a variety of useful atp files. On a unix computer, the standard atp files are found in '$PERL5LIB/Xray/atp/'. With Window 95/NT or MacOS, they are found in the 'atp' folder, which is in the 'Xray' folder under the perl's installation site. The standard atp files are:
| file | purpose |
| feff.atp | input file for FEFF6. |
| feff8.atp | input file for FEFF8. |
| p1.atp | the entire contents of the unit cell in the P 1 space group. |
| unit.atp | the overfilled contents of the unit cell. |
| atoms.atp | the current data as an ATOMS input file. |
| dafs.atp | the results of a DAFS simulation. |
| powder.atp | the results of a powder diffraction simulation. |
| absorption.atp | the results of an absorption data calculation. |
| molecule6.atp | input file for FEFF6 using atomic coordinates of a molecule. |
| molecule8.atp | input file for FEFF8 using atomic coordinates of a molecule. |
| template6.atp | empty template for a FEFF6 input file. |
| template8.atp | empty template for a FEFF8 input file. |
| pdb.atp | a cluster of atoms using Brookhaven Protein Data Bank format. |
| alchemy.atp | a cluster of atoms in the alchemy format. |
| xyz.atp | a cluster of atoms in the xyz format. |
| geom.atp | a 'geom.dat' file for use with FEFF's path finder. |
| symmetry.atp | a symmetry table for the current space group. |
| gnxas_cry | input file for the GNXAS CRYMOL program in the ``CRY'' format. |
| gnxas_sym | input file for the GNXAS CRYMOL program in the ``SYM'' format. |
| formulas.atp | a file containing math expressions for every atom site. |
| test.atp | an ATOMS diagnostic file. |
In ATOMS you choose your output file by specifying the name of the atp file and, optionally, the filename for the output file. For example, in an ATOMS input file, a symmetry table is chosen by inserting this line
output symmetry symmetry.dat
The syntax of that line is
output atp_type file_name
and the atp_type is the name of the atp file without
the '.atp' extension. In TkATOMS and WebATOMS, the
symmetry file would chosen by selecting it from the appropriate menu.
ATOMS scans your computer for available atp files and checks your selection against the available options. There are two sites that ATOMS searches for atp files. One is the standard location mentioned above. The other is the user's personal ATOMS configuration directory. On a unix computer, the personal configuration directory is '$HOME/.atoms'. On Windows and MacOS, there is no personal directory since the user may freely alter the standard atp files.
You may create entirely new atp files and place them in your configuration directory. You may also alter standard atp files by copying them to your configuration directory and editing them. ATOMS searches the personal directory before the standard directory. If, for example, 'feff.atp' is found in both places, the one from the personal directory will be used.
The next section describes the syntax of the atp file. The final section describes a simple major mode for Emacs which can be used as an aid in writing successful atp files.
The only hard rule about atp files is that their names end in the characters '.atp'. When ATOMS goes searching for template files, it only finds those which end in '.atp'. There are several heuristics that TkATOMS follows when displaying the available atp files. It is important that you are aware of these heuristics should your make your own atp files and wish to use them with TkATOMS.
ATOMS reads atp files with a one-pass filter. This means that the atp file is read line-by-line, and at each line ATOMS follows the instructions contained on that line for generating output. The atp syntax thus consists of a set of tokens which ATOMS replaces with the indicated text. Each token consists of a tagword surrounded by angle brackets. A token might also contain arguments which are also placed within the angle brackets. Here are examples, one of a token without arguments and one of a token with arguments:
<rmax>
<potentials :ipots species>
Note that tokens with no arguments contain no white space.
Arguments are always words beginning with a colon and followed by the
value of the argument. Values can consist of multiple words, in which
case they must be enclosed in double quotes.
A shortcoming in the current parser is that the close angle bracket > cannot be used as part of an argument value. For example, something like ``>>>'' is not an acceptible prefix for <id>, <corrections> or other tokens.
As ATOMS parses through the atp file, it replaces each token by the
appropriate text. Any text in the atp file that is not a token is
passed through unfiltered. Here is an example atp file. This atp
file shown in Fig. ![[*]](cross_ref_motif.png)
is for a unit cell output file.
This generates output shown in Fig. .
<com> This file is part of the Atoms distribution.
<com> Atoms is copyright (c) Bruce Ravel 1998.
<com> This is the atoms template file for an p1.inp file
<com> Atoms homepage: http://feff.phys.washington.edu/~ravel/atoms/
<com>
<meta :file "p1.inp file" :precision 9.5 :output "p1.inp">
<id :prefix "! ">
<titles :prefix "title = ">
space p 1 ! original space group: <space>
a = <a> b = <b> c = <c>
alpha = <alpha> beta = <beta> gamma = <gamma>
core = <central> edge = <edge> rmax = <rmax>
atoms
! elem x y z tag
<list :style unit>
<elem> <x> <y> <z> <itag>
Figure : atp file for overfull unit cell output
! This p1.inp file was generated by Atoms, version 3.0beta1
! Atoms written by and copyright (c) Bruce Ravel, 1998
title = Copper example
space p 1 ! original space group: F m -3 m
a = 3.810 b = 3.810 c = 3.810
alpha = 90.0 beta = 90.0 gamma = 90.0
core = Cu_1 edge = K rmax = 5.0
atoms
! elem x y z tag
Cu 0.00000 0.00000 0.00000 Cu_1
Cu 0.00000 0.50000 0.50000 Cu_2
Cu 0.50000 0.00000 0.50000 Cu_3
Cu 0.50000 0.50000 0.00000 Cu_4
Figure : Overfull unit cell output
Note that lines beginning with the <com> token are treated as
comments and are ignored. Normal text is passed through unaltered and
tokens are replaced by appropriate values. The line after the
<list> token is treated as the format for the list which
follows.
Spaces and tabs in atp files are treated like any other text. That is, if the atp parser finds spaces in the atp file, it will write spaces to the output file. If the parser finds tabs, it will write tabs.
The parser is not very smart about knowing which tokens are reasonable for which kinds of output. For example, the <rmin> token is relevant to DAFS output but not for other kinds of output. Irrelevant tokens are not guaranteed to possess sensible values. It is thus the responsibility of the atp file author to write a sensible atp file. This is particularly true for atp files used for molecule output. Several tokens relevant to a crystal cell may translate to peculiar values for a molecule.
There are five categories of tokens in the atp syntax.
Type 1 tokens are simply replaced by their appropriate values. These tokens never take arguments and must have no white space between the tagword and the angle brackets. If a type 1 token appears among normal text, then, in the output, the normal text will appear with the substituted text inserted for the token.
<a>
(type 1)
Replaced by the a lattice constant in s.
<abslist>
(type 1)
Replaced by a comma separated list identifying the sites occupied by
the absorber species. This is useful for GNXAS output.
<alpha>
(type 1)
Replaced by the lattice angle in degrees.
<b>
(type 1)
Replaced by the b lattice constant in s.
<beta>
(type 1)
Replaced by the lattice angle in degrees.
<c>
(type 1)
Replaced by the c lattice constant in s.
<central>
(type 1)
Replaced by the two letter element symbol of the central atom.
<class>
(type 1)
Replaced by crystal class of the specified space group.
<ctag>
(type 1)
Replaced by the tag of the central atom.
<dspacing>
(type 1)
Replaced by d-spacing of the crystal at the currently selected
reflection.
<edge>
(type 1)
Replaced by the alphanumeric symbol of the chosen absorption edge.
<eedge>
(type 1)
Replaced by the energy of the absorption edge in eV.
<emax>
(type 1)
Replaced by the upper bound of the energy grid in a DAFS simulation.
<emin>
(type 1)
Replaced by the lower bound of the energy grid in a DAFS simulation.
<energy>
(type 1)
Replaced by the energy in eV at which the calculation is made. This
is mostly useful for powder diffraction simulations.
<estep>
(type 1)
Replaced by the spacing of the energy grid in a DAFS simulation.
<iedge>
(type 1)
Replaced by the index used by FEFF to denote the absorption edge.
<fxc>
(type 1)
Replaced by the formula for the x component of the central atom.
<fyc>
(type 1)
Replaced by the formula for the y component of the central atom.
<fzc>
(type 1)
Replaced by the formula for the z component of the central atom.
<gamma>
(type 1)
Replaced by the lattice angle in degrees.
<given>
(type 1)
Replaced by the space group symbol as specified by the user.
<gnclass>
(type 1)
Replaced by one letter symbol for the crystal class of the specified
space group as used by GNXAS.
<gnid>
(type 1)
Replaced by a one-word identifier as needed in the second line of
the GNXAS CRYMOL input data. This is the first word of
the first title line. That is a lame way of doing it, but...
<lamdba>
(type 1)
Replaced by the wavelength in ngstroms at which the calculation
is made. This is mostly useful for powder diffraction simulations.
<n>
(type 1)
Replaced by a line break.
<nabs>
(type 1)
Replaced by the number of unique sites occupied by the absorbing
atom.
<nclus>
(type 1)
Replaced by the number of atoms in the output atom list.
<redge>
(type 1)
Replaced by the energy of the absorption edge in Rydbergs.
<reflection>
(type 1)
Replaced by the Miller indeces of the currently selected reflection,
enclosed in parentheses.
<rmax>
(type 1)
Replaced by specified radial size of the output cluster.
<rnn>
(type 1)
Replaced by the distance to the nearest neighbor atom.
<rss>
(type 1)
Replaced by the radius of the small sphere. The small sphere
radius is a modest distance suitable for calculating the
self-consistent potentials in FEFF8. <rss> equals a
multiplier times <rnn>, the near neighbor distance. The
value of the multiplier is the value of the :sphere
argument to the <meta> token and defaults to 2.2.
<space>
(type 1)
Replaced by the canonicalized space group symbol.
Type 2 tokens are replaced by a multi-line list. The following line is used to specify the format of the rows in the list. Type 2 tokens usually require arguments.
<dafs>
(type 2)
Replaced by the list from a DAFS simulation. It takes no arguments.
The list can contain any of <e>, <ascr>,
<a>, <r>, <i>, <p>,
<inc>. This really must only be used with DAFS simulation
output. If given cluster data, this will produce very strange
output.
<list>
(type 2)
Replaced by an atom list which uses the following line to format the
rows of the list. <code> can take one argument,
:style, which can be one of cluster,
neutral, unit, or overfull. If you use
an overfull list, then you can also use the argument
:margin which is used to define nearness to the wall, edge,
or corner of the unit cell. It defaults to 0.1. The list can
contain any of <x>, <y>, <z>,
<r>, <ipot>, <znum>, <tag>,
<itag>, <elem>, <inc>, <1bou>,
or <n>. Some other possible list items are
<valence>, <color>, <b>,
and <file>. These last six are various site
attributes which will be used in future versions of ATOMS.
<potentials>
(type 2)
Replaced by the potentials list required in a FEFF input file,
using the following line as the format for the list. The main
argument is :ipots which is used to specify the assignment
of unique potentials and which takes one of species,
tags, or sites. The default is species.
The list can contain any of <ipot>, <znum>,
<elem>, <l>, or <stoi>. Note that the
potentials list must come before the atoms list in an atp file.
FEFFATOMS does. This list only
serves a purpose in FEFF input files. The argument :gcd
can take 0 or 1 and tells ATOMS whether to divide a greatest
common denominator out of the stoichiometry column. If the argument
:display is 0, ATOMS will compute the potential indeces
but not display the potentials list in the output file. This is
necessary if the atoms list uses the potential indeces even if the
potentials list is not displayed.
<powder>
(type 2)
Replaced by the list from a powder diffraction simulation. It takes
no arguments. The list can contain any of <tth>,
<th>, <a>, <asqr>, <r>,
<i>, <p>, <mult>, <lp>,
<h>, <k>, <l>, or <inc>. This
really must only be used with powder simulation output. If given
cluster data, this will produce very strange output.
Type 3 tokens specify list elements. In the context of a list, they behave like type 1 tokens. That is, they are simply replaced by their substitutions. Outside the context of a list, type 3 tokens are treated as normal text, i.e. they are not substituted (unless there is a type 1 token of the same name - for example <a>.
<1bou>
(type 3)
Replaced by the one bounce flag. This is only relevant for
'geom.dat' files.
<a>
(type 3)
Replaced by the amplitude of a DAFS or powder simulation.
<ascr>
(type 3)
Replaced by the amplitude squared of a DAFS or powder simulation.
<b>
(type 3)
Replaced by the size of the thermal spheroid.
<color>
(type 3)
Replaced by the color assigned to a site.
<e>
(type 3)
Replaced by the energy in a DAFS simulation.
<elem>
(type 3)
Replaced by the two letter element symbol of the site.
<file>
(type 3)
Replaced by the name of the auxiliary file for a site.
<fx>
(type 3)
Replaced by the formula for the x component of a site.
<fy>
(type 3)
Replaced by the formula for the y component of a site.
<fz>
(type 3)
Replaced by the formula for the z component of a site.
<h>
(type 3)
Replaced by the h Miller index of a peak in a powder simulation.
<i>
(type 3)
Replaced by the imaginary part of a DAFS or powder simulation.
<inc>
(type 3)
Replaced by an incrementing index.
<ipot>
(type 3)
Replaced by the potential index of the site.
<itag>
(type 3)
Replaced by the tag associated with the site plus its cluster index,
separated by an underscore.
<k>
(type 3)
Replaced by the k Miller index of a peak in a powder simulation.
<l>
(type 3)
Replaced by an angular momentum value appropriate to the element.
This is 1 for Ne and lighter, 2 for Kr and lighter, and 3 for the
rest of the periodic table. This is relevant for potential lists in
FEFFl Miller index
of a peak.
<lp>
(type 3)
Replaced by the Lorentz-polarization correction of a peak in a
powder simulation or an energy point in a DAFS simulation.
<mult>
(type 3)
Replaced by the multiplicity of a peak in a powder simulation.
<n>
(type 3)
Replaced by a line break.
<occ>
(type 3)
Replaced by the occupancy of a site.
<p>
(type 3)
Replaced by the phase of a DAFS or powder simulation.
<r>
(type 3)
In the context of a cluster, this is replaced by the radial distance
from the central atom. In a DAFS or Powder list, it is replaced by
the real part of the calculation.
<stoi>
(type 3)
In the context of a potential list, this is replaced by the number
of atoms of this potential index in the unit cell. In the context
of a atom cluster list this is replaced by number of atoms in the
unit cell of that unique potential. This information is used by
FEFF8 to compute the Fermi energy and the self-consistent
potentials. If the :gcd argument to the
<potentials> token is set to 1, then the stoichiometry
numbers will be reduced by a factor of their greatest common
denominator.
<tag>
(type 3)
Replaced by the tag associated with the site.
<th>
(type 3)
Replaced by the value of a peak in a powder simulation.
<tth>
(type 3)
Replaced by the 2 value of a peak in a powder simulation.
<utag>
(type 3)
Replaced by the unique tag associated with the site. In general
these are the same as the tags, but If the user assigns tags that
are not unique, ATOMS will append some characters to assure that
every site has an individual utag. The utags are used when
constructing site coordinate formulas.
<valence>
(type 3)
Replaced by the formal valence of the atoms occupying a site.
<x>
(type 3)
Replaced by the x coordinate of the atom.
<y>
(type 3)
Replaced by the y coordinate of the atom.
<z>
(type 3)
Replaced by the z coordinate of the atom.
<znum>
(type 3)
Replaced by the elemental number of the site.
Type 4 tokens are replaced by multi-line blocks of text. Type 4 tagwords should be paced on lines by themselves and so should not be used among normal text in the manner of type 1 tokens.
<corrections>
(type 4)
Replaced by the results of the calculations using the McMaster
tables. One optional argument is :prefix which specifies
the string that is inserted before the id line (for instance an
appropriate comment character). If the prefix contains spaces, use
double quotes to delimit it. The other argument is
:prettyline. If this is 1, then the corrections will be
separated from the surrounding text by a line of dashes and
asterisks. These lines are omitted if the value is 0.
<ease>
(type 4)
Replaced by lines used by the EXAFS Analysis
System for Emacs.
The :file argument takes the type of the output file.
Typically this will be either feff or atoms. The
:prefix argument takes the local variables prefix
recognized by EASE. This should be the same string as the
input-mode-variable-comment variable in EASE.
<gncell>
(type 4)
Replaced by lines describing the cell axes and labels in the form
needed for the GNXAS CRYMOL input data.
<id>
(type 4)
This writes out some information identifying the version of Atoms
that generated the output file. The only argument is
:prefix which specifies the string that is inserted before
the id line (for instance, an appropriate comment character). If
the prefix contains spaces, use double quotes to delimit it.
<resource>
(type 4)
Replaced by a line identifying the absorption data resource in use.
One optional argument is :prefix which specifies the string
that is inserted before the resource information.
<shift>
(type 4)
Replaced by a line specifying the shift vector. This is a type 4
rather than type 1 token so that it can be omitted if the shift
vector is (0,0,0). One optional argument is :prefix which
specifies the string that is inserted before the word ``shift'' (for
instance an appropriate comment character).
<titles>
(type 4)
Replaced by the user-supplied title lines. The only argument is
:prefix which specifies the string that is inserted before
the id line (for instance, an appropriate comment character). If
the prefix contains spaces, use double quotes to delimit it.
Type 5 tokens are not translated into actual text. These are either comments or specify meta-data used by the atp parser.
<com>
(type 5)
Anything following this token on a line will be ignored by the
parser.
<meta>
(type 5)
This line will not be passed to the output file, but it contains
information relevant to the construction of the output file. The
arguments are :output which provides the default output
file name; :precision indicates the precision of the output
floating point numbers; :file which specifies a character
string describing the current output file; :incbegin which
is the first number which used by the <inc> token;
:list which tells the parser what kind of atom list will be
used by the <list> token; <:feff> which takes the
version number of FEFF that this atp file is appropriate for or 0
otherwise; :sphere which takes the multiplier used to
compute <rss>; :gnxas which is 1 only for output
files intended to be used with the GNXAS CRYMOL
program; and :occupancy which takes 1 is the atoms list in
the output file should display dopants and 0 if it should not. The
:list argument is needed because the atp parser is a
one-pass filter. Some tokens that may appear before the
<list> token will need to know what kind of list will be
used later in the file. Setting :occupancy to 0 is
necessary for a 'feff.inp' file, but 1 is used to save dopant
information in the output file.
Atom lists are the raison d'être of ATOMS. Consequently ATOMS offers several kinds of atoms lists which are specified in the atp file by the <list> token. The :style argument is used to select the list type. The list types are
.
The line following the <list> token specifies the format of the list. The list can contain any the following tokens <x>, <y>, <z>, <r>, <ipot>, <znum>, <tag>, <itag>, <elem>, <inc>, or <ibou>. Note that FEFF requires that the first four columns be <x>, <y>, <z>, and <ipot>.
In the FEFF input file, the assignment of unique potentials in made in the list following the POTENTIALS card. This list is made using the <potentials> token in the atp file.
The <potentials> token takes one argument, :ipots. The following line in the atp file is the format of the potentials list. The list consists of any of the following tokens: <ipot>, <znum>, <elem>, <l>, or <stoi>. Note that FEFF6 only requires <ipot> and <znum>. <stoi> is optional but highly recommended in the FEFF8 input file.
The :ipots argument can take one of three values, species, tags or sites. These indicate how ATOMS should assign unique potentials from the contents of the unit cell. species means that each atomic species should receive its own unique potential. tags means that each unique atom tag should receive its own potential. sites means that each unique crystallographic site should receive its own potential.
Here's an example. With this input file:
title YBCO: Y Ba2 Cu3 O7
space P M M M
rmax=5.2 a 3.823 b 3.886 c 11.681
core=cu2
atom
Y 0.5 0.5 0.5
Ba 0.5 0.5 0.184
Cu 0 0 0 cu1
Cu 0 0 0.356 cu2
O 0 0.5 0 o
O 0 0 0.158 o
O 0 0.5 0.379 o
O 0.5 0 0.377 o
Using the species option results in this potentials
list:
POTENTIALS
* ipot Z element
0 29 Cu
1 39 Y
2 56 Ba
3 29 Cu
4 8 O
Using the tags option results in this potentials
list:
POTENTIALS
* ipot Z element
0 29 Cu
1 39 Y
2 56 Ba
3 29 cu1
4 29 cu2
5 8 o
Using the sites option results in this potentials
list:
POTENTIALS
* ipot Z element
0 29 Cu
1 39 Y
2 56 Ba
3 29 cu1
4 29 cu2
5 8 o
6 8 o
7 8 o
8 8 o
Note that the sites option is a poor choice for this
material. FEFF only allows 7 unique potentials other than the
central atom. In this case the tags option combined with a
judicious choice of site tags in the input file would be more
appropriate.
This list is used to format the output of a DAFS simulation. The list can present any of the amplitude, amplitude squared, real part, imaginary part, and phase of the calculation as a function of energy. You can also count data points with the <inc> token.
If you use an atp file with the <dafs> list with cluster data from the ATOMS cluster expansion or any any other kind of atoms list data, you will get very strange results. There are some heuristics built into ATOMS to try to avoid that situation, but the best solution is just not to do it!
This list is used to format the output of a powder diffraction simulation. The list can present any of the amplitude, amplitude squared, real part, imaginary part, and phase of each peak in the calculation. You can also list 2theta, theta, the multiplicity, the Lorentz-polarization correction, and the Miller indeces of each peak. You can also count peaks with the <inc> token.
If you use an atp file with the <powder> list with cluster data from the ATOMS cluster expansion or any any other kind of atoms list data, you will get very strange results. There are some heuristics built into ATOMS to try to avoid that situation, but the best solution is just not to do it!
In the 'etc/' directory of the ATOMS distribution you will find a file called 'atp.el'. This is a program for use with Emacs which defines an editing mode for creating and maintaining atp files.
To use 'atp.el', move it to a location where Emacs looks for lisp programs. For system-wide use, that would be the 'site-lisp/' directory under the Emacs installation. For personal use, put in the place where you keep your own lisp programs. Once installed, byte-compile it. This can be done by this command at the command line:
emacs -batch -q -f batch-byte-compile atp.elor by editing the file and doing M-x byte-compile-file.
You will need to put some lines in the system 'site-start.el' file or in your own '.emacs' file to enable the use of atp-mode in Emacs:
(setq load-path (append (list ("\\.atp$" . atp-mode)) load-path))
(autoload 'atp-mode "atp" "Atoms template mode." t)
With these lines, any file with the '.atp' extension will
be loaded into atp-mode.
Several features are offered by atp-mode which aid in making atp files which work well. Tagwords and arguments are colored by atp-mode using font-lock. This is useful as a sort of spell-checker. If tokens are not colored, then they are misspelled. Atp-mode also supplies completion and description functions for keywords and arguments. Here is a list of all the key-bindings in atp-mode:
| key | description |
|---|---|
| M-tab | Complete word at point. |
| M-? | Write a one-line description of the word at point in the echo area. |
| C-c C-k | Display all tagwords with short descriptions in a help buffer. |
| C-c C-c | Check the syntax of the current file. |
| C-c C-n | Jump to the next error found by the syntax checker. |
The syntax checker invoked by C-c C-c is pretty simple minded. It checks that all words within angle brackets are actually tagwords, that tokens which take arguments have the allowed arguments, and that the argument values are sensible. The jump function moves point to the beginning of the line containing the next error found by the syntax checker. I intend to keep the syntax checker up to date as tokens are added to the parser.