Demeter Overview

Demeter object

The main class, inherited by virtually every other object in the Demeter system. It handles object creation, destruction, and access. It also provides a number of command generators used by more than one other object and a unified regular expression tool for dealing with the multitude of text in the atoms/feff/ifeffit universe.

Target applications might include:

Graphical user interfaces (artemis replacement)
High-throughput systems
An "experiment watcher", i.e. a program that watches disk space, slurps in each new data file that appears, and adds it to a merge
Specialized analysis problems (e.g. Shelly's mkfit or PRB, 73, p. 184121 (2006))
One-off data processing
Feff backend to a ball-n-stick viewer

Items marked with a heart contain something novel, those items marked with a wrench need work, the blank piece of paper indicates something on which work has not started.

Data objects

Everything about importing mu(E) or chi(k) data, removing background, Fourier transforming, and other data processing.

Defaults

Find sensible defaults for all processing parameters and do sanity checks on user-provided values.

Various methods for finding e0, including Ifeffit's default, fractional step height, tabulated value, zero crossing of the second derivative, and setting to an arbitrary value.

Background removal, merging, calibrating, aligning

Process

Truncate, rebin, smooth, noise, convolution, etc. Pretty much everything from Athena's Data menu.

Analysis

Linear combination, log-ratio/phase-difference, principle components, peak fitting. This is unimplemented at this time.

Theory objects

Generic structure file import

This is unwritten. It will use OpenBabel, once I have written a feff.inp parser. Then it will be possible to convert among feff.inp and structure files for other applications. For instance conversion of Protein Data Bank file to a feff.inp file will be trivial. Even better, any OpenBabel-enabled application will then be able to write out feff.inp files.

Atoms objects

Implements (yet again!) the functionality of Atoms. Write a feff.inp file, which can be used by the Feff object or used to run feff independently.

Reads atoms.inp files, CIF files, and provides an API.

Currently not implemented: for every site in the cluster, store a set of formulas for x, y, and z for computing how the atoms got to that position in the cluster. This can then be used to parameterize fits in terms of crystal distortions and will work well with the features of the ScatteringPath object

Absorption

This module provides hooks into calculation using Xray::Absorption, including fluorescence corrections, total cross-sections, and edge steps.

Feff objects

Feff input file

For transparency with non-Demeter uses of Feff, the feff.inp file will remain the unit of currency. However, the file will be parsed and stored in an internal format. The input file will then be rewritten as needed to run parts of feff.

List of ScatteringPath objects

The ScatteringPath object is the result of rewriting Feff's pathfinder. The two weaknesses of this pathfinder implementation are:
- Considerably slower than feff's pathfinder
- Currently limited to 4 legged paths (but that is due to laziness, not a fundamental limitation -- eventually there will be no nleg limit, unlike feff)
- No access (at this time) to the plane wave approximation used to compute the importance factors, which are used to limit heap size and to provide a rough estimate of the spectral weight of each path.
The strengths of this implementation include:
- Information about degenerate paths is not lost. Each ScatteringPath object includes a complete list of paths that were found to be degenerate.
- Degeneracy is defined fuzzily. Using a tunable parameter, you can define how far apart two paths must be in distance and/or angle to be considered distinct. This pathfinder thus bins similar paths in a way that should reduce the complexity of modeling a distorted material.

Run/replace parts of Feff

The functionality of Feff6 is split between native Feff and Demeter. The parts identified as being Demeter chores have been entirely re-implemented in Demeter. The parts that are identified as being Feff chores involve Demeter writing a temporary feff.inp file with only one of the CONTROL flags toggled on, then running feff6 as a system call.
1. Read input file (Demeter)
2. Compute potentials (Feff)
3. Run pathfinder (Demeter)
4. Write paths.dat file (Demeter)
5. Run genfmt (Feff)
Genfmt will typically be called in a just-in-time fashion by Demeter. That is, feffNNNN.dat files will typically not be generated until they are needed for a fit, sum, or a plot and Demeter will keep track of whether anything about the theory has changed and re-generate feffNNNN.dat files as needed.

Fitting objects

The Fit object is defined rather simply at the user's end. It is simply a collection of three lists, a list of Data objects, a list of Path objects, and a list of GDS objects. Each Path object must be associated with a Data object, thus the objects themselves contain sufficient information to structure the fit.

Extensive sanity checking happens even before sending the first command to Ifeffit. Many errors are easy to flag, for example defining but not using a guess parameter, or using but not defining a GDS parameter. The fit will fail to run and a useful (hopefully) error message will be returned if the sanity checks fail.

List of data objects

This is a list of Data objects, as described elsewhere in this document.
The characteristic value or [cv] of the data object becomes useful in the context of a Fit object. When the fit is evaluated, math expressions for Path object path parameters associated with this Data object are re-written to use the cv. For example, if sigma2 path parameters are defined as debye(theta, [cv]) and each data set has a cv equal to the temperature at which the data were collected, then the sigma2 values for that data set will be rewritten with the temperature replacing [cv].

List of GDS objects

The are the parameters of the fit. There are several types:
- guess: a parameter to be varied
- def: a parameter to be evaluated throughout the fit
- set: a parameter which is evaluated once at the beginning of the fit
- lguess: a local guess which is expanded into a unique guess parameter for each data set that uses it
- skip: defined but not used
- after: like a def, but evaluated once the fit is complete
- merge: a parameter imported while merging projects, but of an ambiguous type. a fit cannot continue while merge parameters are unresolved

List of Path objects

This may or may not be linked with a ScatteringPath object from the Theory subsystem. That is, the Path object may link to a file that already exists or it may link to a ScatteringPath object. If it links to a ScatteringPath object, the theory subsystem will be used to generate the feffNNNN.dat file. Otherwise, it reads a pre-existing feffNNNN.dat file from disk.

Happiness

After a fit finishes, Demeter evaluates a semantic (i.e. non-statistical) parameter for the fit based on the R-factor, path parameter values, restraints, and other aspects of the fit. This parameter is a tunable, ad hoc measure of how happy the fit will make the person running the fit. These factors go into determining the happiness of a fit:
- It should have a small R-factor.
- The number of variables should be considerably less than the number of independent points.
- The S02 and sigma^2 path parameters should not be negative.
- The e0, deltaR and sigma^2 path parameters should not be too big.
Happiness is an entirely semantic (i.e. non-statistical, ad hoc, and non-publishable) parameter which attempts to quantify all of the above.

Plotting objects

This object provides access to all the features of a plot of data that have nothing to do with how the plot is actually made -- things like line colors, axis labels, legend location, and so on.

PGPLOT

This is the Ifeffit plotting backend. Communication between Demeter and PGPLOT is no different than any other communication with Ifeffit.

Gnuplot, Grace, etc

Unimplemented

Dispose

All interaction with Ifeffit (and thus PGPLOT) is handled passed through a single choke point. All upstream methods are text generators and that text is sent to a disposal method, which is inherited by every other module in the package.

This allows any pre- or post-processing of the commands to happen in a transparent way. For instance, command on their way to ifeffit are pre-processed to remove as many line breaks as possible and to condense white space, all of which significantly speeds things up. In the future, the disposal method will handle any magic required to send plotting commands to other plotting backends.

templates

All interaction with Ifeffit, as well as all atoms.inp and feff.inp output is handled through templates using Text::Template. These resemble PHP scripts -- they are snippets of executable perl interspersed with normal text. This adds a layer of complexity to the whole Demeter stack, but it provides a very nice flexibility. For instance, templates exist which will write out a fit in the language of the old feffit program. I am hopeful that using templates will make the upgrade path to Ifeffit 2.0 very simple, once it comes along.

All plotting is also handled via templates. It should be possible to add new plotting backends. For instance, templates can be used to generate gnuplot scripts which are then piped to gnuplot.

Configuration object

This is the configuration subsystem. This inherits from the Demeter object, but is a singleton. An instance of the perl interpreter will have only on Config object.

This reads from the config files in lib/Ifeffit/Demeter/configuration. At start-up, Demeter parses the configuration files and stores all of the information (default values, descriptions, etc). The local demeter.ini file can be used to establish user preferences. Methods are provided for querying values and other information and for reading and writing the ini file.

IFEFFIT