WebAtoms: Convert crystallographic data into a Feff input file ... on the web!

WEBATOMS is a application which can be run locally or hosted on a web server and accessed through your browser. It is available at GitHub.

To access WebAtoms on the web

Point your browser at any of these servers:

  1. http://millenia.cars.aps.anl.gov/webatoms/

If you would like your installation included in this list, let Bruce know by opening an issue at the GitHub site.

To run WebAtoms locally

  1. Clone a copy from the GitHub site or download the latest zip file.
  2. Assuming you have perl installed on your computer, you will need to install the Dancer web framework, perl's YAML tool, Demeter, and all of their dependencies.
  3. Launch the application by doing perl bin/app.pl at the command line.
  4. Point your browser at http://localhost:3000

To deploy WebAtoms on your server

  1. Clone a copy from the GitHub site or download the latest zip file.
  2. Assuming you have perl installed on your computer, you will need to install the Dancer web framework, perl's YAML tool, Demeter, and all of their dependencies.
  3. Follow the instructions for deploying a Dancer application appropriate to your web server.

Installing dependencies

cpanm -S Dancer to download and install Dancer and its dependencies. cpanm -S YAML to download and install YAML and its dependencies. The -S flag uses sudo to do the actual installation.

For DEMETER, follow the instructions at the Demeter homepage.

If you have any problems deploying WEBATOMS on particular servers or accessing it with particular browsers, please open an issue at the GitHub site.

If you have any suggestions or corrections for this manual, also open an issue at the GitHub site.

Using WebAtoms

When run in your browser, WEBATOMS (like Gaul) is in three parts. Across the top of the window are a bunch of useful links, including the link back to the empty WEBATOMS application in the upper left. On the left is a form to be filled in with crystallographic data. On the right is the response area, which will (hopefully!) be filled with a feff.inp file or some other useful crystallographic calculation.

_images/webatoms.png

Fig. 1 WEBATOMS, running locally, after importing a CIF file for Ga2O3

The sort of data expected by WEBATOMS is the same as the command line and desktop versions of ATOMS and is explained in some detail in the ARTEMIS manual in the chapters on the Atoms window and on crystallography for EXAFS.

As an aid to using WEBATOMS, hint text will appear when the mouse lingers over the different elements of the form. For instance, when the mouse lingers over the text box for entering the cluster size, the hint text will read “The radial extent of the cluster written to the feff.inp file”.

The shift vector is used to recenter a crystal from a non-standard setting into a setting that will be recognized by WEBATOMS' crystal engine. This often causes confusion and is discussed here in some detail.

Once you are done entering crystal data, leftclick click the Compute button. The corresponding feff.inp file will be displayed in the response area on the right.

To save the contents of the response area, leftclick click the Save as button. You will be prompted for the name and location of the save file on your computer.

If you find any bugs while using WEBATOMS or you think that crystallographic data is being interpreted incorrectly, please open an issue at the GitHub site.

Entering crystallographic data

There are several ways of importing crystallographic data in this application:

  1. Manually enter your crystal data into the form.
  2. You can import from a CIF or atoms.inp file which resides locally on your computer. To do this, leftclick click the Browse button to post a file selection dialog and select a file from your computer. Then leftclick click the Submit crystal data button. Your data will be imported and the result will be shown in the response area.
  3. Enter a URL to a CIF or atoms.inp file in the text box below the Browse button. Hit Return to fetch that file from the internet. Your data will be imported and the result will be shown in the response area.
  4. Use the /?url= syntax in the URL for the WEBATOMS application, e.g. http://webatoms.server/?url=http://www.crystallography.net/cod/1535967.cif. Your data will be imported and the result will be shown in the response area. In this way, you can hook WEBATOMS up to other web or desktop applications.

Todo

  1. Need to streamline file import this so that the second button click is not necessary
  2. Upload directly from a file, i.e. http://webatoms.server/?file=/path/to/1535967.cif or some such. Although care should be taken, as this can expose files inappropriately to the internet.
  3. Say something sensible when a file is neither atoms.inp nor CIF.
  4. Lots more testing for error conditions.

Note that one- or two-letter symbols are typically used to identify the element at each site. However, full names (e.g. “oxygen”) or Z numbers (e.g. “8”) can be used as well. Names must be spelled correctly according to British English spelling (which is odd, I suppose, but the tool used to recognize element names was written using British English – so “aluminium”, not “aluminum” as we sensible Yanks say).

Output options and saving files

There are a number of kinds of output that can be generated by WEBATOMS. While a feff.inp is the most common, there are other options:

  • A FEFF6 input file
  • A FEFF8 input file, also suitable for FEFF9
  • An ATOMS input file
  • An ATOMS input file using the P1 space group and with the fully decorated unit cell
  • A file detailing absorption calculations made using tables of X-ray cross-sections
  • A file detailing the space group of the crystal
  • A file with the same cluster of atoms as the feff.inp file, but in the XYZ format, which may be useful for input into a ball-and-stick viewer
  • A file with the same cluster of atoms as the feff.inp file, but in the alchemy format, which may be useful for input into a ball-and-stick viewer
  • An “overfull” file, which has the fully decorated unit cell expressed in Cartesian coordinates and includes all of the atoms that sit near cell walls and corners – this is intended for import into a ball-and-stick viewer
  • A diagnostic file with the state of the application – probably only useful for troubleshooting

Selection between FEFF6 and FEFF8 style files is made with the ipot style menu. This menu offers each of the three ipot styles for each of FEFF6 and FEFF8.

The results of the WEBATOMS calculation are displayed in the response area. Clicking the Save as button will write using the browser's standard mechanism for using or saving files.

The Save as button at the bottom of the response area uses javascript to write the contents of the response area to a file on the local machine. The only third-party script used is the ubiquitous jQuery. All other javascript that is executed by the local computer is either embedded in the html file or distributed with WebAtoms and served by the same server that is running WEBATOMS itself. Beyond jQuery, no other javascript used by WEBATOMS comes from somewhere else on the Web.

If saving from the response area is not working, it is possible that you have execution of javascript disabled in your browser.

Issues with CIF files

If you find any bugs while using WEBATOMS or you think that crystallographic data is being interpreted incorrectly, please open an issue at the GitHub site.

Multi-record CIF files

A single CIF file can contain more than one crystal structures. Currently WEBATOMS has no way to prompt you to choose which record from a CIF file you want to import. WEBATOMS will always import the first record. Here's an example of a CIF file with 2 records.

Partial occupancy

WEBATOMS cannot handle partial occupancy of crystallographic sites. Read this for more information the topic of dopants.

Imperfect parsing of CIF files

It is certainly possible that you might come across a valid CIF file which is not parsed correctly by the tool used by WEBATOMS. In this situation, submit an issue at the github site and include the CIF file in question (or a link to where that CIF file can be found).

Imperfect recognition of CIF files

Currently a CIF file is recognized only if it's file name ends in .cif. That's dumb and easy to foil, but that's how it works right now. Happily, WEBATOMS is more deft at recognizing atoms.inp files.

Troubleshooting

If you find any bugs while using WEBATOMS or you think that crystallographic data is being interpreted incorrectly, please open an issue at the GitHub site.

You have N unique potentials, but Feff only allows 7.

This usually happens when you have a lengthy list of unique sites and are using the tags or sites ipot style. You can find a discussion of ipot styles in the Artemis manual.

Sites generate one or more common positions and their occupancies sum to more than 1.

This is likely to happen when importing a CIF file with partial occupancy of lattice sites. WEBATOMS is not able to generate a feff.inp file with consideration of partial occupancy. You can find a discussion of dopants in the Artemis manual. The need for a shift vector is another possible culprit.

Your symbol could not be recognized as a space group symbol.

This section of the Artemis manual has a complete list of symbols recognized by WEBATOMS.

Lattice constant was not a number / Lattice constant was negative

Lattice constants must be positive numbers and must be written in a way that are obviously interpretable as numbers. Localization is not respected – the decimal mark is a dot (.), not a comma, momayyez, apostrophe, decimal separator key symbol, space, or any other symbol.

Lattice angles must also be positive numbers. So too the three radius parameters.

Note that site coordinates can be negative, but must also be obviously interpretable as numbers using a dot for the decimal mark.

Symbol for site N is not a valid element symbol

Element symbols for the sites must be the standard two-letter symbols as found on any English-language periodic table (or Hephaestus). Full names (e.g. “oxygen”) or Z numbers (e.g. “8”) can be used as well, however names must be spelled correctly.

Note that site tags can be any string and need not be related to the element symbol, although only the first 10 characters will be used. Also, tags should not include white space.

Citing WebAtoms

Use

  • Bruce Ravel. ATOMS: crystallography for the X-ray absorption spectroscopist. Journal of Synchrotron Radiation, 8(2):314–316, 2001. doi:10.1107/S090904950001493X.

or

  • B. Ravel and M. Newville. ATHENA, ARTEMIS, HEPHAESTUS: data analysis for X-ray absorption spectroscopy using IFEFFIT. Journal of Synchrotron Radiation, 12(4):537–541, 2005. doi:10.1107/S0909049505012719.


DEMETER is copyright © 2009-2016 Bruce Ravel – This document is copyright © 2016 Bruce Ravel

This document is licensed under The Creative Commons Attribution-ShareAlike License.

If DEMETER and this document are useful to you, please consider supporting The Creative Commons.