Demeter

Description Perl tools for X-ray Absorption Spectroscopy
Demeter > Perl Modules > Demeter::ScatteringPath
Source

NAME

Demeter::ScatteringPath - Create and manipulate scattering paths

VERSION

This documentation refers to Demeter version 0.9.26.

SYNOPSIS

   $sp_object -> new(feff=>$feff, string=>$string);
   $sp_object -> evaluate;

Those are the only two attributes provided to the object. Everything else is computed from those two.

DESCRIPTION

This object handles the abstract representation of the scattering path. This is part of Demeter's theory subsystem, unlike Demeter::Path, which is part of Demeter's fitting subsytem. This object is used by Demeter::Feff's path finder and just-in-time path calculator.

This object requires that a Feff object has already been created and fully populated. That is either done by the Feff object's rdinp method or in some other manner. These objects are created during the Feff object's pathfinder method. Once a tree of scattering paths is created from the Feff object's atoms list, the tree is traversed and a ScatteringPath object is made from each visitation of the tree. The tree is completely depopulated, transfering each ScatteringPath object to a heap. ScatteringPaths are removed from the heap and placed onto a well-ordered list of paths. As the list is created, the paths are collapsed by degeneracy.

Although you may interact with ScatteringPath objects extensively in your programs, typically creation is left up to the Feff object's pathfinder method. Similarly, you will find that you rarely set attributes, but often get them.

ATTRIBUTES

feff

A reference to the Feff object from which this ScatteringPath was created. parent is an alias for feff.

string

A string denoting the route this path takes through the cluster. This string has a very specific form. The first and last tokens in the string represent the absorber and can be almost anything. A plus sign (+) is typical. Each intermediate token is the index in the Feff objects atoms list for that atom in the scattering path. The tokens are joined by dots. For example, a ScatteringPath that represents the path from the absorber to the 7th atom in the list to the 23rd atom in the list and back (a double scattering path) would have this string:

   +.7.23.+

These numbers are interpreted by referring to the Feff object contained in the feff attribute. Typically, the value of this attribute is the first degenerate scattering geometry found by the path finder.

nkey

This is a integer constructed from the atoms indeces that is used to sort the scattering paths in the heap a predictable manner.

rleg

This is a reference to a list of path lengths in the path.

beta

This is a reference to a list of beta angle in the path.

eta

This is a reference to a list of eta angle in the path.

nleg

This is the number of legs in the path, stored for easy reference.

halflength

This is the half path length of this path. This is the primary sorting criterion.

heapvalue

This is a value required by and used by the Heap algorithm. It is computed using the halflength class method from Demeter::Tools.

n

This is the degeneracy of this path after the paths have been collapsed.

degeneracies

This is a reference to a list containing the string attribute of each ScatteringPath object that was collapsed into this one.

fuzzy

This is the fuzzy path length. It is set to the average of the lengths of the nearly degenerate paths. For truly degenerate paths, the half length and the fuzzy length will be the same.

METHODS

Accessor methods

The accessor methods of the parent class, get and set are used my this class.

attributes

This returns a list of all ScatteringPath object attributes.

  print join(" ", $sp -> attributes), $/;
    ==prints==>
       nleg string heapvalue group nkey weight etanonzero rleg fs
       degeneracies n randstring beta eta feff halflength fuzzy type
savelist

This returns a list containing the subset of all ScatteringPath object attributes that need to be saved when a Feff calculation is serialized.

  print join(" ", $sp -> savelist), $/;
    ==prints==>
       nleg string group nkey weight etanonzero rleg fs degeneracies
       n randstring beta eta halflength fuzzy type

Evaluation methods

Once a ScatteringPath object if defined by the new method and given feff and string attributes, the object must be evaluated. For reasons of efficiency, the evaluation is not done automatically, so the example given for the evaluate method should become your common idiom for using this object.

evaluate

This method sets most attributes for the object based on the values of the feff and string attributes. It calls the remaining methods in sequence.

   $sp_object -> new(feff=>$feff, string=>$string);
   $sp_object -> evaluate;
compute_nleg_nkey

Determine the number of legs of this path and compute the nkey from the atoms in this path. Set the nleg and nkey attributes.

compute_halflength

Determine the half path length of this path and set the halfpath attribute. Note that the Demeter::Tools::halflength class method is used to compute this.

compute_beta

Compute the beta and eta angles for this path and set the beta and eta attributes.

Textual reporting methods

pathsdat

This method writes out a paragraph in the format read from the paths.dat file by genfmt

  print $sp_object -> pathsdat(\%args);

This method takes an optional argument which is a hash reference. The hash has can have these keys:

index

the numerical index of this path in the sense of NNNN from feffNNNN.dat

angles

a boolean, true measn to write out the rleg, beta, and eta columns to the paths.dat file. note that those columns are optional -- feff does not read them

string

the string (in the sense of the ScatteringPath string method) to be used to expand into a paths.dat paragraph. use the all_strings method to get the strings of all degeneracies for this SP object

all_strings

This method returns a list of text strings of the sort returned by the string method. These can be used to reconstruct the geometry of any of the degenerate paths subsumed into this ScatteringPath object.

  @strings = $sp_object -> all_strings;
all_degeneracies

This returns a list of text strings. The list contains the list from the all_strings method with each list element passed through the intrplist method.

intrplist

Compute the interpretation line from the string attribute. This looks something like this:

   [+] O_1    Ti_1   O_1    [+]

With no argument, this returns the interpretation line for the primary path:

  print $sp_object -> intrplist;

Alternately, you can provide a string from the list returned by the all_strings method to generate the interpretation line for that degenerate path:

  print $sp_object -> intrplist($some_string);

Heap methods

These are the two methods required by the Heap module.

heap

This is used to set and access the heapvalue attribute.

cmp

This is the comparison method used to order the items on the heap. It sorts first by half path length, then by nleg, then by the output of the betakey method, and finally by the nkey.

In practice this means that paths are ordered by increasing path length, then by increasing nleg. In the case of collinear paths, it is guaranteed that the single scattering paths will come before the doubles which will come before the triples. The sort by beta assures that forward scattering paths come before paths which scatter at other angles.

Finally, the nkey portion of the sort makes it clear which path from a degenerate set will be selected as the representative path. This sort is done in the order the atoms appear in the Feff object's atoms list. For example, for the single scattering from the first shell, the representative path will always be the one that scatters from the first atom from the first coordination shell to appear in the atoms list.

COERCIONS

When the reference to the ScatteringPath object is used in string context, it returns the group name, like other Demeter objects.

When the reference to the ScatteringPath object is used in numerical context, it returns the half length of the path from the halfpath method.

DIAGNOSTICS

Demeter::ScatteringPath: \"$key\" is not a valid parameter

You have tried to set or get an invalid ScatteringPath attribute.

Demeter::ScatteringPath::compute_halflength: feff and string attributes unset

You have attempted to compute a halflength without defining the path geometry.

ScatteringPaths from different Feff objects

You have attempted to compare ScatteringPath objects associated with different Feff objects.

CONFIGURATION AND ENVIRONMENT

See Demeter::Config for a description of the configuration system. The pathfinder parameter group is used to configure the behavior of this module.

DEPENDENCIES

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

BUGS AND LIMITATIONS

A few features have not yet been implemented:

And testing has been limited.

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

Copyright (c) 2006-2018 Bruce Ravel (http://bruceravel.github.io/home). All rights reserved.

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.

generated by Pod::ProjectDocs