(Jump to start of text)


Conventions and acknowledgements

The best way to learn how to use ATHENA is to use ATHENA. Poke at the buttons, poke at the menus, try things just to see what happens. And above all, remember the physical and mathematical meanings of your data and of the data analysis techniques and think about how actions in ATHENA relate to those meanings.

ATHENA is a powerful and versatile program capable of supporting almost all of your common (and not-so-common) XAS data processing chores. It is not, however, a particularly intuitive program. I doubt that any XAS program could be intuitive. On top of that, ATHENA has accumulated lots of features over the years. Many of these features are necessary for high-quality data processing, others are bells and whistles intended to make data processing more convenient or more fun.

This document attempts to be a comprehensive overview of all of ATHENA's features. There are lots of words, but also lots of pictures. Feel free to jump around and to focus on the parts most directly relevant to your immediate needs. I hope you find this document and the program helpful.

Layout and typesetting conventions

Here is a summary of fonts, colors, and symbols used to denote different kinds of text. Note that some of these may appear the same in certain presentation media.

Points that require special attention are written inside of attention-grabbing boxes.

This symbol indicates a section describing one of ATHENA's features that I consider especially powerful and central to the effective use of the program.

This symbol indicates a section with difficult information that newcomers to ATHENA might pass over on their first reading of this document.

The html version of this document makes use of HTML 4.1 character entities (mostly Greek symbols) and will not display correctly in very old browsers.

POD -- the native documentation for Perl and the format used internally in ATHENA -- is not able to display graphics. Everywhere that a graphics file is displayed in the other document formats, a bit of text showing the name of the image file and the caption of the figure is displayed in the POD. Here is what it looks like when one of the pod documents is displayed by a pod viewer:

(Image file: athena_main.png) The parts of the ATHENA.

In most cases, this will convey sufficient information given that you will have ATHENA open in front of you. If you need to see the picture, you can seek out the image file by name or look at the corresponding part of the html or PDF versions of the document.


I have to thank Matt Newville, of course. Without IFEFFIT there wouldn't be an ATHENA. One afternoon over coffee, Julie Cross and Shelly Kelly lit the spark that eventually lead to this document. Some content of this document was inspired by an upcoming XAS review article by Shelly Kelly and Dean Hesterberg, which I have had the pleasure of editing (and, apparently, swiping from). I have a huge debt of gratitude to all the folks on the IFEFFIT mailing list. Without the incredible support and wonderful feedback that I've received in the last six years ATHENA would be a shadow of what it is today.

The following great software tools were used to create this document:

All screenshots were made of ATHENA or the PGPLOT window on my KDE desktop, mostly using some version of the Orangio theme for deKorator. The screenshots of spreadsheets made from a report file and an LCF fit report are displayed in OpenOffice.

The images of the Tholos temple on the front page and the Klimt painting Pallas Athena in the navigation box of the html document are from http://www.artchive.com.

The image used as the ATHENA program icon is from “Heracles and Athena. Tondo of an Attic red-figure kylix, 480-470 BC, from Vulci” from the Staatliche Antikensammlungen in Munich, Germany. The image is in the public domain and was found on Wikimedia Commons. The image used as the HEPHAESTUS program icon is from Reubens' “Vulcan forging Jupiter's thunderbolts” from the Museo Del Prado, Madrid Spain. This image is also in the public domain and also from Wikimedia Commons.

Data citations

Installing Athena on your computer

Linux, BSD, and other unixes
It is not especially hard to build ATHENA from source code. The procedure is explained in detail on this web page: http://cars9.uchicago.edu/iffwiki/BruceRavel/EvolvingSoftware.

Debian and debian-based Linux
Add the repositories listed on this page: http://wiki.mr.aps.anl.gov/ObtainingSoftware. This can be done either by editing `/etc/apt/sources.list' directly or by adding repositories using the system package manager (e.g. Adept on ubuntu). Once these are included as repositories, the “horae” package, which contains ATHENA, can be installed.


An MSI installer package is available at http://cars9.uchicago.edu/iffwiki/Downloads. Installation is very simple. Just double click on the installer and follow the instructions. If you are installing onto a machine for which you do not have administrator privileges, you should choose a part of the disk that belongs to you when asked about the installation location.

For those with ActiveState Perl installed on their windows machines, the “horae” source code can be installed using the Perl Package Manager. In the Perl Package Manager, select “Preferences” from the Edit menu, then click on the repositories tab. Add http://cars9.uchicago.edu/~ravel/ppm/ as a new repository. The “horae” package should now show up as an installable package.

An installer package is available at http://cars9.uchicago.edu/iffwiki/Downloads. Installation is very simple. Just double click on the installer and follow the instructions.

Building this document from source

Obtaining the document source

The source files and all images files for this document can be downloaded by SVN. To grab the source, you will need an SVN client on your computer. This command checks a copy of the source out and downloads it onto your computer:

    svn co

This document is written using The Template Toolkit. It requires the perl interpreter and a fairly complete installation of version 2 of The Template Toolkit to build. If TT2 is not available as a package for your system (it is available as a pre-compiled package for many versions of Linux; a ppm file for ActivePerl on Windows exists; a Fink package for OSX exists) it can be downloaded from its website and installed by hand or downloaded using perl's CPAN utility. You will also need to install the Image::Size, and Syntax::Highlight::Perl modules. Compiling the LATEX version of the document will require a fairly complete LATEX installation as I make use of many styles, including amsmath, amsfonts, floatflt, fancybox, fancyhdr, keystroke, varioref, and hyperref. (teTeX compiles the document without any problem. The texlive package may complain about not being able to generate two postscript font sets. Those two warning can be safely ignored by simply hitting Return when pdflatex pauses to complain. As far as I can tell, ignoring this problem has no impact on the document. I have no experience building the PDF document on any system other than linux.)

Once TT2 and the other modules are installed, building the document should be quite simple. TT2's ttree program is used to recurse the through the directory structure containing the templates. The `bin/build', `bin/tex', and `bin/pod' scripts are wrappers around ttree. They invokes a number of important command line options and pass any further command line options to ttree.

TT2 was chosen for this project because it is an excellent templating tool. A templating tool was chosen because the strong separation of format and content was attractive to me. The template source is used to generate html and PDF versions of the document as well as the pod format used by ATHENA's internal document viewer.

Contributions to the document are extremely welcome. The very best sort of contribution would be to directly edit the source templates and commit your changes to the SVN repository. The second best sort would be a patch file against the templates in the repository. If TT2 is more than you want to deal with, but you have corrections to suggest, I'd cheerfully accept almost any other format for the contribution. (Although I have to discourage using an html editing tool like FrontPage to edit the html directly. Tools like that tend to insert lots of additional html tags into the text, making it more difficult for me to incorporate your changes into the source.)

Building the html document

After downloading and unpacking the source for this document, you must configure it to build correctly on your computer. This is simple:


To build the entire document as html

./bin/build -a

Individual pages can be built by specifying them on the command line:

./bin/build bkg/norm.tt

Building the LaTeX document

The LATEX document is built by

./bin/tex -a
cd tex/
pdflatex athena.ltx
pdflatex athena.ltx

You need to run pdflatex two or three times to get all of the section numbering and cross referencing correct. The varioref package, used to handle cross-referencing, is sometimes a little fragile. If you see the following error message: simply hit return. The message should disappear when you recompile the document.

! Package varioref Error:
vref at page boundary 142-143
(may loop).

A version of the PDF document suitable for printing on a grayscale (i.e. without color) printer can be made using this sequence of commands:

cd images/
cd ../
./bin/texbw -a
cd texbw/
pdflatex athena.ltx
pdflatex athena.ltx

This first bit converts all of the images used in the document to grayscale using ImageMagick. The “texbw” version of the document is nearly identical to the normal LATEX document, except that the style file and several templates are changed to remove all color from the document. Compiling the version in the texbw/ directory results in a PDF file that is suitable for a non-color printer.

This output target was created for the 2008 APS summer school. The cost saving of printing the ATHENA document in black-and-white rather than color for each of the students was quite significant.

Building the pod document

The pod document, ATHENA's internal document format, is built by

./bin/pod -a

Individual pages can be built by specifying them on the command line:

./bin/pod bkg/norm.tt

Using the document with Athena

The pod and html document files can be used by ATHENA, but they must be installed in the correct location. To do this, run the install script that comes with the document package. This will use an ATHENA module to determine the correct location, then copy over all relevant files. Once installed ATHENA will display the html document in either a web browser or a pod viewer depending on the values of the “Doc:prefer” and “Doc:browser” preferences.

(Jump to start of text)