Using the Tk Version

   
Overview of the Tk Version

TkATOMS is the graphical interface to the ATOMS package. It is written in perl/Tk application and includes interfaces to programs for calculating atomic clusters of the sort need by FEFF as well as several other calculations of interest to the x-ray absorption spectroscopist.

The TkATOMS window, shown in Figure , is split into two halves. At the top is a notebook widget, with several notecards for controlling the different programs. The bottom panel is used to specify crystallographic data, the user-supplied titles, and the absorption edge.

Figure : The TkATOMS window as it appears when first launched.

 

Many areas of the TkATOMS windows have help balloons attached. By letting the mouse linger for a half second over any of these areas, a balloon pops up with a few words explaining the purpose of the widget near the mouse. In the case of text entry fields, only the label has a help balloon attached. This is because it's really annoying when a help balloon pops up over a text field that you want to type into. See Chapter  for a way of disabling the appearance of the help balloons.

Most actions in TkATOMS are initiated using the mouse-1 button, although mouse-3 is also used for some things. On a three button mouse, mouse-1 is usually bound to the left button, mouse-2 to the middle, and mouse-3 to the right, although this layout is configurable. Because some people prefer to use a left-handed mouse layout, I will always refer to the mouse buttons by their numbers. On a two button mouse, as is common on Microsoft Windows systems, the left and right buttons are usually mouse-1 and mouse-3 respectively. mouse-2 may be simulated using a keystroke/mouse-press combination. Sometimes pressing the chord between the mouse buttons simulates a mouse-2 event on mice so equipped. On a one button mouse,^8.1 mouse-2 and mouse-3 are keystroke/mouse-press combinations usually involving the Apple and control keys. Some mice have more than three buttons (as does my own beloved trackball). TkATOMS does not use any higher-numbered buttons.

   
The Crystallography Panel

The bottom section of the TkATOMS, shown in Figure , is used to enter crystallography data. These data are common to all the programs run using TkATOMS. Consequently, this panel is visible regardless of which notecard is visible above it.

There are three sections in this panel. At the top is a text entry field for entering title lines describing your crystal. These titles lines may be written to output files. Below the title box, is a grid of widgets for basic data about the unit cell. There are boxes for entering the space group symbol, the lattice constants and the lattice angles. There is a also a drop down menu for choosing the absorption edge. As described in Section , you only need enter those lattice constants and angles which are necessary to describe your space group. See Section  for a description of what happens when you push the button labeled ``Browse Space Group''.

Figure : The Crystallography Panel

 

At the bottom is a scrolled table for entering the positions of the unique crystallographic sites. Initially this table has 4 lines, thus can hold data about 4 unique sites. More lines can be added to the end of the table by clicking on the button labeled ``Add 1 site''. The element symbol, x, y, and z coordinates, and site tag are as described in Section . The central atom of the cluster is chosen by clicking on the radio button next to the site of the central atom in the left-most column of the table. At the right side of the table are buttons which can be used to clear the data in that site. If you continue scrolling to the right, you will find additional columns for entering other details about a site. Currently, most of these additional columns are unused by ATOMS, but I expect that they will be used in future releases. There is no limit to the number of sites that you include in this list.

It is convenient to enter data into this table without having to shift your hands between the keyboard and mouse. To this end, the arrow keys in combination with the shift key can be used to navigate the fields in the site list. For example shift-right-arrow moves the focus one entry field to the right. The other arrow keys behave similarly. All four directions wrap around the table, thus hitting shift-right-arrow several times will eventually return you to the same entry field. See the description for the variable $unused_modifier in Chapter  for details on how to customize the arrow key sequences.

There is no key for simply deleting a site. However, a site will be ignored by TkATOMS if the element column is left blank.

At the right side of the table are sliders for setting the occupancy of the site. This is how dopants can be introduced into TkATOMS. Please read Section  and The EXAFS Analysis Using FEFF and FEFFIT course (the URL is in Section  ) for a discussion of the use of dopants in ATOMS.

   
The Program Panel

The upper panel of the TkATOMS window uses a notecard metaphor to allow you to select among several different programs which use the crystallography data displayed in the lower panel. These programs are

Atoms

Generate ordered lists of atomic coordinates

Absorption

Calculate quantities of interest using tables of x-ray absorption coefficients.

DAFS

Simulate the energy dependence of the anomalous scattering from a crystal using tables of normal and anomalous structure factors.

Powder

Simulate a powder diffraction scan at a specified energy.

Molecule

Convert structure data for a molecule into a FEFF input file.

   
The Atoms Notecard

This notecard contains widgets for controlling different aspects of the ATOMS program.

Figure : The Atoms Notecard

 

The Run Atoms button

This button is rather self-explanatory. Once you have filled in all the widgets with the appropriate data, press this button to calculate a list of atomic coordinates. Before actually calculating, ATOMS will verify that all the data you have entered is sensible, determine whether your chosen space group might need a shift vector, and verify that your lattice constants are appropriate to the chosen space group. If everything checks out, the list will be calculated and displayed in the output display window, described in Section .

The Cluster size entry box

If you select a type of output that generates a radially sorted cluster of atoms, then the size of the radial cluster is determined by the contents of this box. If you leave it blank, the cluster size defaults to the smaller of 7 Å and 1.1 times the length of the largest lattice constant. If you choose a really huge number, then your output file will contain a huge number of atoms. Even worse, the time and memory required to calculate a huge list scale as the third power of this number. Usually 10 Å or less is quite enough.

The Shift Vector entry boxes

These boxes are used to enter the coordinates of a vector which is needed in certain situations. Read Section  for a complete discussion of the shift vector. If you use a space group which might require a shift vector, TkATOMS will pop up a dialog box with a message similar to that given in Figure .

Note that the contents of the shift vector entry boxes are evaluated. This means that you are allowed to type things like 1/8 rather than 0.125.

If the space group specified in the crystallography panel is one which commonly takes a shift vector, that vector can be inserted into these boxes using a function in the Data menu.

The I0 fill gas sliders

These are used to indicate the contents of the I0 chamber and are used by ATOMS to calculate the self-absorption and I0 corrections to the EXAFS data. These calculations are described in Chapter . The units on these sliders are percentage of the total pressure in the chamber.

The Output file types menu

TkATOMS allows you to select from a list of possible output files. The type of output file is selected by choosing the output file type from a drop-down menu. The list of output file types is generated at startup time by scanning the ATOMS installation directory and the users configuration directory for files which end in '.atp'. These atp, or ATOMS template, files are used by ATOMS to format its output files. See Chapter  and Appendix .

The menubar

At the top of the notecard, you will see a menubar. Clicking Mouse-1 on any item in the menubar will drop a menu. The File menu is used to load and save input files and to quit TkATOMS. Loading and saving uses the standard Tk::FileDialog widget. Its use is straightforward.

The Clear menu is used to clear out part or all of the data in the ATOMS notecard and in the lattice panel. The Data menu is used to perform various data operations. The Help panel provides access to the on-line help system.

   
The Absorption Notecard

This notecard is used to make calculations using tables of x-ray absorption data. These are the same calculations may be written to the top of ATOMS output files except that, using this notecard, you can consider dopants and fractional occupancy. Occupancy data is not used when making atom lists using the ATOMS notecard.

Figure : The Absorption Notecard

 

Six calculations are made on this notecard. These are

Total Absorption

The inverse of the total absorption is the absorption length of the sample, i.e. the distance over which incident x-rays at the chosen absorption edge attenuate e-fold.

Edge step

The change in absorption over the absorption edge energy. The inverse of this number is the sample thickness which yields a unit edge step in a transmission experiment.

Density

This is the mass of the contents of the unit cell divided by the volume of the unit cell.

Normalization correction

Normalizing EXAFS data by the value of the edge step introduces a small error into the measured $\chi(k)$. This error is proportional to k², thus it behaves like an additional Debye-Waller factor.

I0 correction

In a fluorescence experiment, the energy response of the I0 detector introduces a small error into the measured $\chi(k)$. This error is proportional to k², thus it too behaves like an additional Debye-Waller factor.

Self-absorption corrections

In a fluorescence experiment, the measured signal is attenuated by the energy dependence of the absorption of the sample. There are two terms, a k² term and an amplitude term. These are approximated with the assumptions that the sample is infinately thick and that the measurement geometry is such that the incident and exit angles of the photons are equal.

See Chapter  for a discussion of how these calculations are made.

There are sliders controlling the contents of the I0 chamber on this notecard. These sliders are completely independent of the similar sliders on the ATOMS notecard. The I0 and self-absorption corrections are only calculated if one or more of the sliders is non-zero.

All other data regarding the calculation, including the identity of the central atom and the absorption edge, is taken from crystallography panel. Use the occupancy sliders to explore the effects of vacancy and doping on the numbers calculated by this notecard.

The absorption data resource (i.e. McMaster, Henke, Elam, and so on) can be chosen using the radiobuttons on the left side of the notecard. These can be changed at any time, allowing you to compare the different data resources.

The menubar on this notecard is very similar to that on the ATOMS notecard. The one interesting addition is in the Data menu. Using the Absorption Units entry, you can switch between units of inverse centimeters and microns for the total absorption and edge step calculations. These representations are simply reciprocals of one another and scaled appropriately.

   
The DAFS Notecard

This notecard is used to approximate the energy dependence of the amplitude of a diffraction peak as the energy is scanned through an absorption edge. The full complex scattering factor is used. Values for f₀ are taken from the Crommer-Mann tables and the anomalous corrections are taken from the Henke tables, the Chantler tables, the Brennan/Cowen tables or any other data resources provided by 'Absorption.pm' (See Appendix ).

All of the data resources in 'Absorption.pm' neglect solid state effects, thus there is no fine structure in the DAFS simulation. However, knowing the size and direction of the cusp for a particular reflection can be useful information when planning or interpreting an experiment. In the future I plan add the ability to use an external file in place of the absorption data resource for any atom in the unit cell as a way of introducing solid state effects to the simulation. This might be a FEFF calculation or the output of Matt Newville's DIFFKK program.

The calculation is made over an energy range which usually includes the edge energy of one of the elements in the material. The complex scattering of all elements in the material is included in the calculation, even those with edge energies far from the chosen edge energy. Some atoms, particularly heavy atoms, have significant complex scattering components even far from their resonant energies.

Figure : The DAFS Notecard

 

There are five widgets on this notecard:

The Run Button

Press this button to start the calculation.

The Energy Grid box

The three text entry fields in this box are used to determine the energy grid of the calculation. Emin is the number subtracted from the chosen edge energy to determine the lower bound of the calculation. If you choose to calculate at the copper K edge (8979 eV) and set emin to 300, the calculation will start at 8679. Emax is a number added to the edge energy to determine the upper bound of the calculation. In the Cu K edge example, with emax set to 500, the calculation will end at 9479. Estep is used to determine the grid spacing.

The Reflection box

These three fields are used to set the Miller indices of the reflection at which to calculate the DAFS spectrum. you may simply type in the fields or use the up and down arrows to increment and decrement the indeces. Note that one or more of the indeces must be non-0 or else TkATOMS will signal an error.

The Data Resource box

Only those resources which provide anomolous scattering factors (i.e. not McMaster and Elam) are listed in this box. Choose a resource by clicking on it.

The Plotting canvas

The plotting canvas consists of two parts, the progress bar and the plot. As numerical calculations can be rather slow in perl, the progress bar gives you a visual cue as to the progree of the calculation. As the calculation proceeds, this area fills up from the bottom. Usually calculations are fast, but if you choose a very broad energy range or a very tight grid, it may take 10 or seconds.

When the plot finishes, a thumbnail of the calculation is displayed in the plotting space to the right of the progress bar. Do not confuse this with a proper, interactive plotting tool. It is not. The plot shown here is just a crude representation of the calculation. To examine the calculation fully you will need to save the data and plot it using your favorite plotting utility. You have the option of sending the data off to an external plotting package, such as XMgr or IFEFFIT. See Section .

The Data menu in the menu bar has several interesting options for handling the output of a DAFS calculation. You may save the calculation as using the format of the 'dafs.atp' file (the one that comes with ATOMS formats the data as two columns of energy and amplitude squared). You may also output the thumbnail in the plotting canvas to a postscript file.

There is also a (highly experimental as of ATOMS 3.0beta1) mechanism for sending the calculation to an external plotting program. This requires the use of the 'AtomsConfig.pm' file and some voodoo.

   
The Powder Notecard

This notecard is used to simulate an x-ray powder diffraction scan using the crystal data in the lower panel. The full complex scattering factor is used. Values for f₀ are taken from the Crommer-Mann tables and the anomalous corrections are taken from the Cromer-Liberman, Henke, or Chantler tables (or any other data resources provided by 'Absorption.pm', see Appendix ) or without the anomalous corrections.

There are five widgets on this notecard:

The Run Button

Press this button to start the calculation.

The Energy box

You can choose what energy or wavelength the simulation is made at. You can enter any energy in eV or wavelength in Ångstroms in this box or you can choose an anode line energy from the menu below the entry box. The default is the Cu K edge.

The Output file types menu

You can choose the ATP file for formatting the output data.

The Data Resource box

Only those resources which provide anomolous scattering factors (i.e. not McMaster and Elam) are listed in this box. Choose a resource by clicking on it. You can suppress the anomalous corrections by choosing None.

The Max Order box

You can enter the maximum order of the calculation, 12 by default, in this box. You may need to increase this for unit cells with long dimensions.

The Plotting canvas

A cartoon of the diffraction pattern is displayed after the calculation finishes. Like the canvas on the DAFS notecard, this is not a real plotting tool, just a toy for visualizing the pattern. If you use one of the external plotting hooks (see Section ), then clicking mouse-1 on the canvas will send the data to the external plotting utility. mouse-3 sends the data out for overplotting.

Figure : The Powder Notecard

 

   
The Molecule Notecard

Not everything in the world is a crystal. This notecard is ATOMS's stab at accommodating the non-crystalline world. For many kinds of materials, e.g./ proteins, organo-metallics, and others, structural data is available in the form of Cartesian coordinates for the atoms in the material. The purpose of this notecard is to read in that kind of data (or to explicitly type it into the appropriate entry boxes) and convert that data into a useful FEFF input file. Please note that this is extremely fragile and incomplete as of ATOMS 3.0beta1. When it works, it's nifty. When it doesn't (which is usual), it behaves very mysteriously.

There are four components on this notecard. The button labeled ``Run Molecule'' does just that, outputting the FEFF input file to the output display window (see Section ). The cluster size box allows you to specify a radial cut off for the atoms in the list. The output file types menu lets you select from available output types. TkATOMS ships with formats for turning thus kind of data into files for FEFF6 and FEFF8. See Chapter  and Appendix  for more details.

The big list is similar to the list in the crystallography panel except that it expects numbers to be entered as Cartesian coordinates in Ångstroms. The radio buttons are used to select the central atom and the core and tag columns serve the same purposes as the similarly labeled columns in the crystallography panel.

The titles and absorption edge for the output file are taken from the crystallography panel. Other data in the crystallography panel is ignored by this notecard.

The column labeled skip in the atoms list contains check buttons. Any site which is checked in this column will be ignored when writing the output file. In the Skip menu in the menubar is a function which pops open a small window which you can use for algorithmically selecting atoms to skip. These skip rules are regular expressions matched against the element symbols or tags or else mathematical expressions matched against the coordinates.

Someday I intend for ATOMS to ship with object methods for reading in various common file formats of non-crystalline structural data, for example ShellX and Protein Data Bank files. Currently, it only knows how to read in alchemy files and a sort of generic file format that I made up. When you try to load data you be asked about what kind of file format the data is in. Heuristics are used to try to guess this. Don't expect fireworks.

   
The Output Display Window

When you select an output file and run ATOMS by pressing the Run Atoms button, a new window appears displaying the output file. This is a simple text editing widget which allows you to alter the output before saving it to disk. An example is shown in Figure .

You may save the file to disk by pressing the Save button at the bottom of the screen. This pops open the same file dialog used to load and save input files. In this case you are offered a default file name which is taken from the atp file used to format the output data.

There are three other buttons at the bottom of the display frame. One dismisses the display frame. Another is labeled Run Feff and is active only when the output file is intended to run feff. However, pressing the Run Feff button doesn't do anything at this time.

The last button is labeled Preserve. Normally, when TkATOMS finishes a calculation with textual output, it empties the display box before displaying the new text. Pressing the Preserve button tells TkATOMS that you want to keep the current display and that a new display box should be opened for the next calculation. There is no limit to the number of display boxes you can have open.

Figure : The Atoms output window displaying an input file for FEFF6.

 

   
The Space Group Browser

The space group browser is fairly easy to use as the status bar at the bottom of the widget always informs the user about what actions are available as the mouse passes over active regions of the widget. Three examples of these messages are shown in Figure .

The opening panel displays the seven crystal classes. This is shown in the left panel of Figure . 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 space group text entry field is displaying a valid group symbol, then that symbol will be displayed as active text. Clicking Mouse-1 on that symbol will jump to the panel describing that symbol.

Figure : The three screens of the space group browser.

 

The second panel displays lists of space groups divided by crystal class. This is shown in the middle panel of Figure . 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 space group text entry field. Clicking mouse-3 will display information about that group.

The last panel is the space group description and is shown in the right panel of Figure . It shows all symbols recognized by ATOMS as describing that group. Clicking mouse-1 on any active text will insert that symbol into the space group text entry field.

At the bottom of the widget are three buttons. The back button causes the previous panel to be displayed. The restore button is only active if the space group text entry field contained a symbol when the browser was first invoked. If so, pressing it will restore that symbol to the space group box in the crystallography panel. The dismiss button hides the SGB widget.

   
External Plotting

The cartoony plots in the DAFS and Powder notecards are adequate as a quick representation of the calculation, but not very useful for serious consideration of the data. Clearly, these little cartoons are no substitute for a real plotting program. Rather than attempt to create a useful plotting utility using perl and Tk, ATOMS provides a flexible tool for shuffling the calculation off to an external plotting program. Currently, there is support for using XMgr and IFEFFIT. Both of these require that the external plotting program be installed and available for use. This external plotting functionality is fairly well tested on Unix. The IFEFFIT interface should work on Windows as well.

   
Using the external plotting hooks

The file 'AtomsConfig.pm' is used to set up the external plotting interface. This file is not installed by default when you install ATOMS, but can be found in the 'etc/' directory of the ATOMS distribution. This file can be used if you put it in your '~/.atoms/' directory on Unix or in 'C:\Perl\site\lib\' on Windows.

Next set the configuration variable $plotting_hook. Depending on whether you wish to use XMGR or IFEFFIT, set it to plot_with_XMGR or plot_with_Ifeffit, depending on which you want to use. This variable can be set by editing your 'atomsrc' file as described in Chapter  or using the configuration tool in TkATOMS, described in Section .

With all that done, you can click mouse-1 on the plot cartoon in either the DAFS or the Powder notecards and the data will be plotted using the external program. The mouse-1 click will clear the external plot before plotting the data. Clicking mouse-3 overplots the data in the external program.

It is fairly easy to integrate a new external plotting tool with TkATOMS if you know a bit of perl. The file 'AtomsConfig.pm' is extensively documented and explains how to write a new plotting hook.

   
Using the Plotter notecard

If you use IFEFFIT as the external plotting program, an additional notecard called ``Plotter'' will be displayed in TkATOMS. This provides an extremely simple, command line interface to IFEFFIT. In the future I hope to make this a more robust and useful tool. FOr the moment it is sufficient to make plots using IFEFFIT, but just barely.

At the top of the notecard is a command line where you can write commands for IFEFFIT. Hitting the return key or clicking on the button labeled Enter send the string to IFEFFIT for processing. The output from IFEFFIT is written to the box below. IN the middle of the notecard are various utility buttons. The Zoom, Unzoom, and Read Data button are simple shortcuts for those IFEFFIT commands. The Next and Previous buttons are used to scroll through the history of commands sent from TkATOMS to IFEFFIT.

Don't expect too much from this notecard and you will not be overly disappointed.

   
The Configuration Window

The menubar in each notecard has a Preferences menu on the right hand side. This menu is used to launch the interactive configuration utility which can be used to modify variables which control the behavior of ATOMS and TkATOMS, to change the colors used by TkATOMS, and to change the fonts used by TkATOMS. The variables, colors, and fonts each have their own notecard in the configuration window. At the bottom of the window are two buttons which are there for all three notecard. The button labeled Save Values will cause TkATOMS to write the current values for the variables, colors, and fonts to an 'atomsrc' file of the sort described in Chapter . The Dismiss button hides the configuration window.

There are help balloons attached to each of the variables, colors, and fonts which may be set using this tool. That should help you make appropriate choices when configuring TkATOMS.

   
Configuring Variables

All of the variables described in Chapter  can be set using the the variables configuration notecard. There are several different kinds of widgets on this notecard. The button labeled Set Variables is used to actually fix the values of the variables to the values indicated by the widgets to the left. This only sets them for the current TkATOMS session but does not save them for future sessions. The Restore button restores all variables to the values from the start of the session.

Figure : The variables configuration window.

 

The variables are set using different types of widgets depending on the nature of the variable. The first several variables are boolean and are turned on by setting the checkbox to its on state and turned off by setting the checkbox to its off state. The next several variables can take a value from a list of possible values, so pop-down menus are provided.

Some variables take files names as values. In that case, a text field is provided for typing in the file name. Also a button labeled Browse will open a file dialog for specifying the file name.

Variables which take arbitrary text as their values have text entry fields.

   
Configuring Colors

The color selector is a bit quirky. Unfortunately the standard color dialog that comes with perl/Tk is not well suited for use with TkATOMS. Thus I adopted elements from it into my color configuration utility.

Figure : The colors configuration window.

 

The basic idea is that you select a color using the sliders and/or list box on the right side of the notecard. When you have found a color that you like for a particular graphical element, click on the Set button for that element. You will notice that the little color box to the left of the name of the graphical element will change to your selected color. When you have found all the colors that please you, click on the Set Palette button. This might take a few seconds, but when done all of your color choices will have propagated through all aspects of TkATOMS. The Restore button will restore TkATOMS to the color configuration it had at the beginning of the session.

If you find a color set that you like, you should press the Save Values button so that next time you start TkATOMS, you will see that color set.

The color selector has several components which you can use to fine-tune all your color selections. The drop-down menu lets you select a color definition scheme. By default red-green-blue (RGB) color values are used, but two other quantizations are available.

The sliders are used to set the values of the red, blue, and green channels (if RGB is used). The best way to understand this is to slide them back and forth and watch the color displayed in the oval change.

 

Table: An attractive alternative color scheme.

widget	color name	RGB triplet	hex value
Foreground	black	(   0,    0,    0)	#000000000000
Background	MistyRose3	(804, 718, 710)	#cdd2b7ceb5c2
Trough	MistyRose4	(545, 490, 482)	#8b857d707b64
Entry	MistyRose2	(933, 835, 824)	#eed8d5c2d2f1
Label	DarkGreen	(   0, 392,    0)	#0000645a0000
Balloon	turquoise	(251, 878, 816)	#4041e0c4d0e5
Button	DarkSlateGray	(184, 310, 310)	#2f1a4f5c4f5c
ButtonActive	SlateGray	(439, 502, 565)	#7062808390a3

 

If your system is running X Windows and so has an 'rgb.txt' file that the color selector can find, it will also display the list box shown in Figure . You can scroll through this list and select named colors by double clicking Mouse-1 on them. The oval will change to that color when after double clicking.

Once you have selected a color, click on the appropriate Set button as described above.

A nice alternative to the default color scheme is given in Table . To try this color scheme out, enter those values using the color configuration window or type the hex values into your 'atomsrc' file.

   
Configuring Fonts

Font configuration is not currently supported in ATOMS 3.0beta1. However you may modify the font variables by editing the runtime configuration file as described in Chapter . See the pod documentation in 'Tk::Font' for more details about available font names.