NAME
VERSION
SYNOPSIS
DESCRIPTION
ATTRIBUTES
METHODS
SERIALIZATION AND DESERIALIZATION
CONFIGURATION AND ENVIRONMENT
DEPENDENCIES
BUGS AND LIMITATIONS
AUTHOR
LICENCE AND COPYRIGHT

NAME

Demeter::Feff - Make and manipulate Feff calculations

VERSION

This documentation refers to Demeter version 0.9.26.

SYNOPSIS

  my $feff = Demeter::Feff -> new(file => 'feff.inp');
  $feff->set(workspace=>"temp", screen=>1);
  $feff->run;
  $feff->intrp;

DESCRIPTION

This subclass of the Demeter class is for interacting with theory from Feff. Computing the phase.bin file is done by Feff via a pipe, as is running the genfmt portion of Feff. Parsing the input file, pathfinding, and generating the paths.dat to control genfmt have been implemented as methods of this object.

ATTRIBUTES

file: The name of a feff.inp file.
yaml: The name of a file containing a serialization of a Feff calculation.
atoms: A Demeter::Atoms object from which a feff.inp file will be generated automatically.
sites: Reference to a list containing all the sites found in the input structure. Each element of the list is a reference to a list containing the site's x, y , and z coordinates, followed by its potential index.
potentials: Reference to a list containing all the unique potentials. Each element of the list is a reference to a list containing the site's ipot, Z-number, and tag.
titles: Reference to a list containing all the title lines.
absorber: Reference to a list containing the x, y, and z coordinates of the absorbing atoms.
abs_index: Index, starting at 0, of the absorber in the sites list.
edge: The edge of the calculation. This can be any of 1, 2, 3, 4, K, L1, L2, or L3.
s02: The S02 value. This can be other than 1, which is a really bad idea for the Feff calculation, but that's how Feff works.
rmax: The Rmax value, i.e. the half length of the longest path.
nlegs: The maximum number of legs of paths to be calculated. In Feff this can be as large as 7. Demeter's implementation of the path finder is currently limited to 4.
rmultiplier: The value of Rmultiplier, an isotropic scaling factor for all atomic coordinates in the atoms list.
pcrit: The value of the plane wave criterion. This is not used by Demeter's pathfinder.
ccrit: The value of the curved wave criterion. This may be used by the genfmt method.
workspace: A valid directory in which to run Feff. Demeter will cd into this directory before writing out a feff.inp file, computing the potentials, running the pathfinder, or running genfmt.
miscdat: The contents of the misc.dat file, slurped up after the phase.bin file is generated.
pathlist: A reference to the list of ScatteringPath objects generated by the pathfinder method.
hidden: This boolean attribute is true if this is a "hidden" Feff calculation. As example of this is the Feff calculation associated with a Demeter::FSPath object. In that case, the Feff calculation is intended to be done completely bihind the scenes and the user will normally not interact with it directly. In the contextof Artemis, this means that an entry in the Feff toolbar will not be shown for the FSPath object.
source: This is a string that is used to identify the provenance of the Feff calculation. The default is "demeter/feff6", indicating that the Feff calculation was handled entirely by Demeter. For a Demeter::Feff::External object, this is set to "external", indicating that the Feff calculation was imported from outside of Demeter.
screen: A boolean controlling whether Feff's output is printed to STDOUT.
buffer: A reference to a array or scalar for containing the output from Feff. This array or scalar can then be handled by the caller.
save: A boolean saying whether to save the minimal feff.inp file after a Feff running step is finished.

METHODS

Accessor methods

This uses the set and get methods of the parent class, Demeter.

Feff replacement methods

rdinp

Parse the feff input file and store its information. It can read from an arbitrarily named file, which is an improvement over Feff itself..

  $feff -> rdinp("yourfeff.inp");

If called without an argument, it will look for feff.inp in the current working directory.

This is triggered when the file attribute is set.

pathfinder

Find all unique paths in the input atoms list. All degenerate geometries will be preserved.

  $feff -> rdinp("somefeff.inp") -> pathfinder;

This implementation of the path finder has two advantages over Feff's implementation.

The degeneracy is determined with fuzziness. Paths with similar, but not equal, half-lengths and/or scattering angles will be grouped together as effectively degenerate. The width of these fuzzily degenerate bins is configurable.
The geometries of the degenerate paths are preserved. This will aid in the identification of paths in a ball-and-stick view and allow easier tracking of how structural distortions propagate into the path list.

There are three shortcomings of Demeter's path finder compared to Feff's:

Implemented in an interpreted language, it is considerably slower. This is exponentially true for larger clusters.
It is currently limited to 4-legged paths. This is not a fundamental limitation, merely a lazy one. Eventually all leggedness limitations will be removed from Demeter's implementation.
Demeter cannot compute the so-called importance factor which is used to limit the size of the heap and to convey approximate information about path size to the user. This is actually a pretty serious problem as it means that one of Feff's most important ways of trimming the size of the pathfinder heap is unavailable to Demeter.

This is not simply a drop-in-place replacement. It actually produces different output than Feff's path finder. It will not miss any of the important paths, but it treats degeneracies differently and will include some small paths that Feff would normally exclude.

pathsdat

Write a paths.dat file from some or all of the ScatteringPath objects found by the path finder.

  $feff -> pathsdat()
  # or
  $feff -> pathsdat(7 .. 13);

With no argument, all paths will be written to the paths.dat file. The optional argument is a list of numbers interpreted as indeces of the list returned by the pathlist method.

Feff running methods

run

This calls potph then pathfinder. It is proving common to chain these two methods, so it seems useful to provide a shortcut.

make_feffinp

Write out a feff.inp file suitable for computing the potentials, running genfmt, or running all of Feff.

  $feff -> make_feffinp("potentials");
    # or
  $feff -> make_feffinp("genfmt");
    # or
  $feff -> make_feffinp("full");

potph

Run Feff to compute the potentials. The make_feffinp method will be run if needed.

  $feff -> potph;

This runs just the first segment of Feff, generating the phase.bin file. Note that, when transfering a feff calculation between machines with different CPU or different operating system, this binary file will not be read correctly (possibly not at all) by Feff on the new machine.

genfmt

Run the third segment of Feff, which imports the phase.bin file and generates a feffNNNN.dat file for every entry int he paths.dat file.

  $feff -> genfmt();
  # or
  $feff -> genfmt(7 .. 13);

The optional argument is a list of indeces passed to the pathsdat method. WIthout that argument, pathsdat is used to write out data for every path found by the path finder.

run_feff

This cds to the directory specified by the workspace attribute and runs feff using whatever feff.inp file is found there. You would usually call the make_feffinp method just before calling this.

  $feff -> make_feffinp("potentials") -> run_feff;

report

Dispose of text, possibly gathered from a Feff run, to the channels specified by the screen and buffer attributes.

  $feff -> report($some_text);

rank_paths

Perform various rankins of the importance of the various paths found using Demeter's pathfinder. One of these is to run Feff on the entire path list and extract the curved wave importance factors from the files.dat file. Other rankings are performed using Demeter::ScatteringPath::Rank. The rankings are stored in the ScatteringPath object.

  $feff -> pathfinder;
  ## some time later ...
  $feff->rank_paths;

Reporting methods

intrp

Write an interpretation of the Feff calculation. This summarizes each path, reporting on the feffNNNN.dat index, the degeneracy, the half path length, and a description of the scattering geometry.

The optional argument is used to add markup to add some style to the text written.

To mark up the interpretation for an html page using CSS

   print $feff->intrp('css');

You will need to define CSS text styles called comment, major, minor, and normal for the header, the major paths, the minor paths, and the small paths respectively. Here is a very simple example:

  .comment {
    font: 1em monospace;
    color: #990000;
  }
  .major {
    font: 1em monospace;
    color: #009900;
  }
  .minor {
    font: 1em monospace;
    color: #775500;
  }
  .normal {
    font: 1em monospace;
    color: #777777;
  }

To mark up the interpretation for LaTeX

   print $feff->intrp('latex');

You will need to define colors called commentcolor, majorcolor, and minorcolor for the header, the major paths, and the minor paths, respectively. One way of defining colors in your LaTeX document is

   \usepackage[pdftex]{color}
   \definecolor{commentcolor}{rgb}{0.70,0.00,0.00}

The argument can also be a hash reference defining some other kind of markup. There are five markup tags:

comment: The beginning of a header line. In the latex style, this is "{\color{commentcolor}\texttt{". In css style, this is "".
2: The beginning of a path of importance level 2. In the latex style, this is "{\color{majorcolor}\texttt{". In css style, this is "".
1: The beginning of a path of importance level 1. In the latex style, this is "{\color{minorcolor}\texttt{". In css style, this is "".
0: The beginning of a path of importance level 0. In the latex style, this is "{\texttt{". In css style, this is "".
close: The markup for the end of a style block. In the latex style, this is two closing curly brackets, "}}". In css style, this is " ".

Here is an example of adding some color when writing to a terminal capable of displaying ANSI color:

    use Term::ANSIColor qw(:constants);
    $style = {comment => BOLD.RED,
              close   => RESET,
              1       => BOLD.YELLOW,
              2       => BOLD.GREEN,
              0       => q{},
             };
    print $feff->intrp($style);

The ANSI color example is not pre-defined so that Term::ANSIColor does not have to be a Demeter requirement. That said, it is probably the most useful style.

Convenience methods

These are simple wrappers around the get accessor.

central: Returns a list of the x, y, and z coordinates of the central atom.
list_of_paths: Returns a list of ScatteringPath objects found by the path finder. This simply dereferences the anonymous array contained in the pathlist attribute and returns the list.
nsites: Returns the number of sites in the atoms list.

SERIALIZATION AND DESERIALIZATION

The Feff object uses YAML for its serialization format. All of the scalar valued attributes are collected into a hash, which is the first thing serialized into the YAML file. This is followed by the array-valued attributes in this order: titles, othercards, potentials, absorber, then sites. Finally each of the ScatteringPath objects are serialized in the order they appear in the pathlist attribute. freeze is an alias for serialize.

  $feff -> serialize($yaml_filename);
    # or
  $feff -> freeze($yaml_filename);

There is a second, optional argument to serialize. If true, the serialization file is written without compression. By default, the serialization file is compressed using the gzip algorithm.

You can deserialize the YAML file and store it in a Feff object and a list of ScatteringPath objects. thaw is an alias for deserialize.

  $feff -> deserialize($yaml_filename);
    # or
  $feff -> thaw($yaml_filename);

CONFIGURATION AND ENVIRONMENT

See Demeter for a description of the configuration system.

DEPENDENCIES

The dependencies of the Demeter system are in the Build.PL file.

BUGS AND LIMITATIONS

Need methods for identifying particular paths, for example "the single scattering path with the phosphorous atom as the scatterer".
Automated indexing currently only works when doing a fit. If you want to plot paths before doing a fit, you will need to assign indeces by hand.
Feff8 functionality is incomplete. For instance, the potentials attribute needs to allow for longer lists for the additional parameters in Feff8.
The edge attribute should recognize M, N, O edges.
Need to keep and iedge attribute, as in the Atoms object
The pathsdat method should accept special arguments, like "SS" for all single scattering paths, or "collinear" for all collinear MS paths.
Look into doing a better job of caching halflengths. Tools::halflength is a significanty fraction of the time spent by the pathfinder.

See Demeter::ScatteringPath for limitations of the pathfinder.

Please report problems to the Ifeffit Mailing List (http://cars9.uchicago.edu/mailman/listinfo/ifeffit/)

Patches are welcome.

AUTHOR

Bruce Ravel, http://bruceravel.github.io/home

http://bruceravel.github.io/demeter/

LICENCE AND COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlgpl.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.