Demeter

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

NAME

Demeter::GDS - Guess, Set, Def, and other parameters for EXAFS fitting

VERSION

This documentation refers to Demeter version 0.9.26.

SYNOPSIS

   $gds_object = Demeter::GDS ->
       new(gds     => 'guess',
           name    => 'alpha',
           mathexp => 0,
          );
   $gds_object -> report;
   ## after a fit....
   $gds_object -> evaluate;

DESCRIPTION

This subclass of the Demeter class is inteded to hold information pertaining to guess, def, set, and other parameters for use in a fit.

ATTRIBUTES

A GDS object has these attributes:

name (string)

This is the name of the parameter. It must respect the conventions for a parameter name in Ifeffit or Larch. They can contain only letters, numbers, '&', '?', ':', and '_' (underscore). They are limited to 64 characters and cannot begin with a numeral.

gds (guess def set lguess restrain after merge skip)

This is one of:

guess

A parameter varied in the fit.

def

A parameter whose math expression is continuously updated throughout the fit.

set

A parameter which is evaluated at the beginning of the fit and remains unchanged after that.

lguess

A locally guessed parameter. In a multiple data set fit, this will be expanded to one guess parameter per data set.

restrain

A restrain parameter is defined in an Ifeffit script as a def parameter but is used as a restraint in the call to the feffit function. In a multiple data set fit, all restraints are defined in the first call to the feffit command.

after

This is like a def parameter, but is not evaluated until the fit finishes. It is then reported in the log file.

merge

A merge is the type given to a parameter that cannot be unambiguously resolved when two Fit objects are merged into a single Fit object. A fit cannot proceed until all merge parameters are resolved.

skip

A skip is a parameter that is defined but then ignored. Setting a variable to a skip is the Demeter equivalent of commenting it out.

mathexp (string)

This is the math expression assigned to the parameter. For a guess or set parameter this is often just a number -- the initial guess.

stored (string)

This is the math expression as provided by the user before any rewriting for local parameters.

bestfit (number)

After the fit is evaluated, this contains the result of the fit for this parameter. This is normally not set explicitly with the set method. Rather it is set using the evaluate method so that the math expression is correctly evaluated by Ifeffit/Larch.

error (number)

After the fit is evaluated, this contains the error on this guess parameter. For all other types, this is 0. This is normally not set explicitly with the set method. Rather it is set using the evaluate method after a fit.

modified (boolean)

This is true if the parameter has been modified but not evaluated.

note (string)

This is a text string -- an annotation -- used to describe something about the parameter.

autonote (boolean)

When this is true, the annotation is set automatically when the parameter is evaluated.

use (boolean)

This is a flag disables the use of a global restraint or a global after when local guess parameters are in play.

METHODS

Object handling methods

The GDS object uses the new, Clone, set, and get methods described in the Demeter documentation.

annotate

This method sets the note and autonote attributes in a stroke. It takes a single argument, the annotation string for the parameter.

   $gds_object -> annotate($string)
   $gds_object -> annotate(q{})

If the string is not empty, the note will be set to the string and the autonote attribute will be set to 0. If the string is empty, the note attribute will be cleared and the autonote attribute will be set to 1. These are completely equivalent to

   $gds_object -> set(note=>$string, autonote=>0);
   $gds_object -> set(note=>q{},     autonote=>1);

but using this method saves you the bother of remembering to toggle the autonote attribute.

Reporting and evaluation methods

write_gds

This returns a string which is the command to define the parameter in Ifeffit/Larch.

   $string = $gds_object -> write_gds

This returns a string something like

   guess enot = 0.0

The first word is the parameter type. "def" is used for after and restrain parameters. Other parameter types (skip and merge) return strings which will not be valid Ifeffit/Larch commands.

report

This returns a one-line string which reports on the value of a parameter after a fit is complete. This method is used in the logfile method of the Fit subclass.

   $string = $gds_object -> report;

The strings returned for the various parameter types are different. All contain the best fit value and the math expression (or initial guess). The error is included for guess parameters.

full_report

This is like the report method, but it returns a more verbose, multiline string and includes the annotation.

   $string = $gds_object -> report;

This is not used in the logfile, but may be useful in an interactive application.

evaluate

This method is called after a fit is performed to evaluate the bestfit and error attributes of the object. It also sets the annotation is the autonote attribute is true. It returns 1 in most cases, but returns 0 for unevaluatable parameter types (skip and merge).

   $is_ok = $gds_object -> evaluate;

This is called as part of the evaluate method of the Fit class on all parameters used in the fit. Thus, it normally does not need to be called explicitly. However, it may be useful in interactive use.

DIAGNOSTICS

Moose type constraints are used on several of the GDS object attributes. Error messages appropriate to the type constrain will be generated.

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

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