NAME

Demeter - Single and multiple scattering paths for EXAFS fitting

VERSION

This documentation refers to Demeter version 0.9.26.

SYNOPSIS

  $path_object -> new();
  $path_object -> set(data     => $dobject,
                      folder   => 'example/cu/',
                      file     => "feff0001.dat",
                      name     => "path 1",
                      s02      => 'amp',
                      e0       => 'enot',
                      delr     => 'alpha*reff',
                      sigma2   => 'debye(temp, theta) + sigmm',
                     );

  $path_object -> new();
  $path_object -> set(data     => $dobject,
                      sp       => $scattering_path_object
                      name     => "path 1",
                      s02      => 'amp',
                      e0       => 'enot',
                      delr     => 'alpha*reff',
                      sigma2   => 'debye(temp, theta) + sigmm',
                     );

DESCRIPTION

This subclass of the Demeter class is for holding information pertaining to theoretical paths from Feff for use in a fit.

ATTRIBUTES

The following are the attributes of the Path object. Attempting to access an attribute not on this list will throw and exception.

The type of argument expected in given in parentheses. Several of the attributes take an anonymous array as the value. In each case, the zeroth element of the annonymous array is the math expressionfor the path and the first element is its evaluation. See the discussion below in "METHODS" for a description of how these attributes interacts with the accessor methods. See also the description of the evaluate method for how the second element of the anonymous array gets set.

The defaults for all path parameter math expressions is 0 except for s02, which is 1. The *_value path parameter attributes contain the evaluation of the path parameter after the fit is made or the path is otherwise evaluated.

For this Path object to be included in a fit, it is necessary that it be gathered into a Fit object. See Demeter::Fit for details.

General attributes

group (string)

This is the Ifeffit or Larch group name used for this path. That is, its arrays will be called group.k, group.chi, and so on. It is best if this is a reasonably short word and it must follow the conventions of a valid group name in Ifeffit or Larch. By default, this is a random, five-letter string.

name (string)

This is a text string used to describe this object in a user interface. While the group attribute should be short, this can be more verbose. But it should be a single line, unlike the title attibute.

parent (Feff object)

This is the reference to the Feff object that this Path is a part of. feff is an alias for parent.

data (Data object)

This is the reference to the Data object that this path is associated with. There exists a default Data object so that you can successfully Fourier transform and plot Path objects which are not associated with a Data object, as might be the case for a sum of paths.

sp (ScatteringPath object)

This is the reference to the ScatteringPath object that is used to generate the feffNNNN.dat file. Once the sp attribute is set, the file and folder attributes will be overwritten based on the settings and actions of the Feff and ScatteringPath objects. To set a specific feffNNNN.dat file, you must also set the sp attribute to an empty string.

folder (string)

This is a string that takes the fully qualified path (in the file system sense) to the `feffNNNN.dat' file associated with this Path object.

If the SP attribute is set, then this attribute will be set automatically and changing it via the Path object's set method will be forbidden.

file (filename)

This is the name of the feffNNNN.dat file associated with this Path object.

If the sp attribute is set, then this attribute will be set automatically.

Index (integer)

This is the path index as required in the definition of an Ifeffit Path. It is rarely necessary to set this by hand. Indexing is typically handled by Demeter. Demeter organization of the fit makes use of lists of Path objects, so you are encouraged to think that way rather than to fret about the path indeces.

include (boolean)

When this is true, this Path will be included in the next fit.

plot_after_fit (boolean)

This is a flag for use by a user interface to indicate that after a fit is finished, this Path should be plotted.

default_path (boolean)

This path will be set to the default path after the fit for the purpose of evaluating def, after, and other parameters. This is only relevant if any def, after or other parameters depend explicitly on path-specific quantites such as reff or the evaluation of the Debye or Eins functions.

pc (boolean)

This is a flag indicating that the phase of this path should be used to perform phase corrected plots.

save_mag (boolean)

When true, this tells Ifeffit to save an array containing the magnitude of chi(k). This is used in ranking paths -- see Demeter::ScatteringPath::Rank.

Path parameters

For each of these (except n and id which do not take math expressions and the array path parameters which do not evaluate to scalars), the first item listed is the attribute which takes the math expression. The second item listed is the evaluation of the math expression after the fit is prefromed. The evaluation cannot be set by hand. Instead you must change the values of GDS objects and re-evaluate the fit using either of the fit or sum methods.

n (number): This is the path degeneracy in the definition of an Ifeffit or Larch path. This is a number, not a math expression. Use the s02 attribute to parameterize the amplitude of the path.
s02 (string)
s02_value (number): This is the amplitude term for the path.
e0 (string)
e0_value (number): This is the energy shift term for the path.
delr (string)
delr_value (number): This is the path length correction term for the path.
sigma2 (string)
sigma2_value (number): This is the mean square displacement shift term for the path.
ei (string)
ei_value (number): This is the imaginary energy correction term for the path.
third (string)
third_value (number): This is the third cumulant term for the path.
fourth (string)
fourth_value (number): This is the fourth cumulant term for the path.
dphase (string)
dphase_value (number): This is the constant phase shift term for the path.
id (string): This is Ifeffit's identification string for the path.
k_array (string): This takes the math expression for the infrequently used k_array path parameter. You really need to know what you are doing to use the array valued path parameters!
amp_array (string): This takes the math expression for the infrequently used amp_array path parameter. You really need to know what you are doing to use the array valued path parameters!
phase_array (string): This takes the math expression for the infrequently used phase_array path parameter. You really need to know what you are doing to use the array valued path parameters!

Feff interpretation attributes

Where possible, these attributes will be taken from the ScatteringPath object associated with the Path.

degen (number)

This is the degeneracy in the feffNNNN.dat file associated with this Path object.

nleg (integer)

This is the number of legs in the feffNNNN.dat file associated with this Path object.

reff (number)

This is the effective path length in the feffNNNN.dat file associated with this Path object.

zcwif (number)

This is the amplitude (i.e. "Zabinsky curved wave importance factor") for the feffNNNN.dat file associated with this Path object.

Note that this is always 0 for paths that come from ScatteringPath objects, since the ScatteringPath objct does not, at this time, have a way of computing the ZCWIF.

intrpline (string)

This is a line of text relating to this path from the interpretation the Feff calculation.

geometry (multiline string)

This is a textual description of the scattering geometry associated with this path.

is_col (boolean)

This is true when the path associated with this object is a colinear or nearly colinear multiple scattering path.

is_ss (boolean)

This is true when the path associated with this object is a single scattering path.

METHODS

The Path object inherits creation (new and Clone) and accessor methods (set, get) from the parent class described in the Demeter documentation.

Additionally the Path object provides these methods:

I/O methods

save: This method returns the Ifeffit or Larch commands necessary to write column data files based on the Path object. See Demeter::Data::IO for details. Only the chi, r, and q options are available for writing Path column data files.

Convenience methods

data

This method returns the reference to the Data object that this Path is associated with. This method is meant to be used with the Data object's data method. Path and Data objects can be put into a loop and the correct Data object can be identified for each kind of object.

  foreach my $obj (@data_objects, @paths_objects) {
     my $d = $obj->data;
     ## do something with $d
  };

Note that this works because Data objects have a data method which self-identifies.

value

This method returns the evaluated value of a path parameter after a fit is made or a path is otherwise evaluated.

   my $val = $path_object->value("sigma2");

rm

Delete the feffNNNN.dat file associated with this Path.

  $path -> rm;

Ifeffit/Larch interaction methods

read_data

This is completely different from the read_data method called on a Data object. Or, it's exactly the same, depending on your perspective. It is not normally necessary to call read_data on a feffNNNN.dat file in the course of data analysis. That file is imported into Ifeffit or Larch as a part of the write_path method.

When read_data is called on a Path object, the Ifeffit/Larch command for reading the feffNNNN.dat file as a column data file is returned. This is useful if you ever need to examine the raw columns of the feffNNNN.dat file.

  $command = $path_object -> read_data;

write_path

This method returns the Ifeffit or Larch commands to import and define a Feff path. It takes a boolean argument which tells the method whether to also generate the Ifeffit or Larch command for converting the defined path into arrays for plotting or other manipulations. That argument is set true as part of the display method, but false when the fit is defined.

  $command = $path_object -> write_path($do_ff2chi);

Information reporting methods

These methods are useful for generating log files and other reports.

paragraph

This method returns a multiline text string reporting on the evaluation of the Path's math expressions. This text looks very much like the text that Ifeffit returns when you use Ifeffit's show @group command.

  print $path_object -> paragraph;

row_main

This method returns a newline-terminated line of text containing the values of several path parameters in a format suitable for making a table of fitting results. The path parameters included in this line are n, s02, e0, sigma2, delr, reff, and the sum of delr and reff.

The optional argument specifies the width of the first column, which contains the path labels.

  print $path[0] -> row_main($width);

With this optional argument, you can scan the path labels before creating the table and pre-size the first column, leading to a much more attractive table. The default width is 10 characters. The row_main_label, row_second, and row_second_label methods also take this same optional argument.

row_main_label

This method returns a newline-terminated line of text suitable for the header of the table made by repeated calls to the row_main method. Something like this will make a nice table

   print $path[0] -> row_main_label;
   print $path[0] -> row_main;
   print $path[1] -> row_main;
   print $path[2] -> row_main;

row_second

row_second_label

This method returns a newline-terminated line of text suitable for the header of the table made by repeated calls to the row_second method. Something like this will make a nice table

   print $path[0] -> row_second_label;
   print $path[0] -> row_second;
   print $path[1] -> row_second;
   print $path[2] -> row_second;

R

This method returns the sum of the reff attribute and the evaluation of the delr path parameter. This:

  print $path_object -> R, $/;

is equivalent to (and fewer keystrokes than):

  ($reff, $delr) = $path_object->get(qw(reff delr_value));
  $R = $reff + $delr;
  print $R, $/;

longest_leg

This returns the length in Angstrom of the longest leg of a path.

  print $path_object -> longest_leg, $/;

This is determined by searching the rleg attribute of the associated ScatteringPath object and returning the longest value.

DIAGNOSTICS

Demeter::Path: "group" is not a valid group name: (F) You have used a group name that does not follow Ifeffit's or Larch's rules for group names. The group name must start with a letter. After that only letters, numbers, &, ?, _, and : are acceptable characters. The group name must be no longer than 64 characters.
Demeter::Path: the sp attribute must be ScatteringPath object: (F) You have set the sp attribute to something other than a ScatteringPath object.

SERIALIZATION AND DESERIALIZATION

See the discussion of serialization and deserialization in Demeter::Fit.

CONFIGURATION AND ENVIRONMENT

See Demeter::Config for a description of the configuration system.

DEPENDENCIES

Demeter's dependencies are in the Build.PL file.

BUGS AND LIMITATIONS

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.

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.