NAME
VERSION
SYNOPSIS
DESCRIPTION
METHODS
TROUBLE REPORTING
CONFIGURATION AND ENVIRONMENT
BUGS AND LIMITATIONS
AUTHOR
LICENCE AND COPYRIGHT

NAME

Demeter::Fit::Sanity - Sanity checks for EXAFS fitting models

VERSION

This documentation refers to Demeter version 0.9.26.

SYNOPSIS

  my $fitobject = Demeter::Fit ->
     new(gds   => \@gds_objects,
         data  => [$data_object],
         paths => \@path_objects,
        );
  $command = $fitobject -> fit;

Before the fit method is run, a series of sanity check on the data contained in the fit object is run. The sanity checks all live in this module.

DESCRIPTION

This module contains all the sanity checks made on a Fit object before the fit starts. This file forms part of the base of the Demeter::Fit class and serves no independent function. That is, using this module directly in a program does nothing useful -- it is purely a utility module for the Feff object.

The user should never need to call the methods explicitly since they are called automatically whenever a fit or a sum is performed. However they are documented here so that the scope of such checks made is clearly understood.

When problems are found, the fit will exit and a descriptive report will be made.

METHODS

The following sanity checks are made on the Fit object:

All data files included in the fit exist.
No data set is obviously used twice in the fit.
All feffNNNN.dat files used in the fit exist.
All guess parameters are used in at least one def parameter or path parameter.
No def or path parameters use parameters which have not been defined.
Binary operators are used correctly, specifically that none of these strings appear in a math expression:
```
   ++    --   //   ***   ^^
```
All function names (i.e. strings that are followed by an open paren) are valid Ifeffit functions.
All data and path objects have unique group names.
All GDS parameters have unique names.
All opening parens are matched by closing parens.
All data paremeters make sense, for example that fft_kmin is smaller than fft_kmax.
The number of guess parameters does not exceed the number of independent points.
The bft_rmin value is not greater than bkg_rbkg.
The R_eff of any path is not far beyond bft_rmax.
Ifeffit's hardwired limits on things like the maximum number of guess parameters and the maximum number of data sets are not exceeded by the fitting model.
No GDS parameters have the names of Ifeffit program variables or other reserved words.
No merge parameters remain unresolved.

TROUBLE REPORTING

The trouble attribute of an Demeter object will be filled with a pipe-separated list of problem codes.

Some error codes contain additional information to further identify the problem. These codes have a keyword separated from the other information by an underscore, making these sufficiently easy to parse on the fly. Indeed, the translate_trouble method of the base object (see Demeter) does just that, so error reporting during a fit is an example of literate programming.

Here are the explanations:

Problems with Data objects

-e: You specified an explicit data file to use in the fit (i.e. not part of a project file) and that file does not exist.
-r: You specified an explicit data file to use in the fit (i.e. not part of a project file) and that data file cannot be read.
namenotunique: The Ifeffit group name of this data group is not unique.
pathdataname: This path has an Ifeffit group name which is used by a Path object.
tagnotunique: The tag of this data group is not unique.
cvnotunique: The characteristic value of this data group is not unique.
kminkmax: kmin is larger than kmax.
rminrmax: rmin is larger than rmax.
rminrbkg: rmin is smaller than the value of rbkg that was used in the background removal.
collision: This data came from the the same source as another data group. You seem to be trying to increase your number of independent points by fitting the same data more than once in a multiple data set fit.
datanopaths: This data has no paths associated with it. You must either assign paths to it or exclude it from the fit.

Problems with Path objects

-e: The path file does not exist (perhaps the Feff calculation was not run).
-r: The path file cannot be read.
spnotexist: The sp attribute is not defined or not set to a ScatteringPath or other Path object, and the path is not using a feffNNNN.dat file directly.
useundef + $pp + $token: The math expression for the $pp path parameter contains an undefined parameter, $token.
binary + $pp + $token: The math expression for the $pp path parameter contains an unallowed binary math operator, $token.
function + $pp + $token: The math expression for the $pp path parameter contains a mathematical function unknown to Ifeffit, $token.
namenotunique: The Ifeffit group name for this path is not unique.
pathdataname: This path has an Ifeffit/Larch group name which is used by a Data object.
parens + $pp: The math expression for the $pp path parameter has unmatched parentheses.
reffrmax: The R effective for this path is much larger than the rmax value chosen for the fit to the data.
nocalc: It seems as though the Feff calculation for this path has not been made yet.

Problems with GDS objects

notused: This is a guess parameter which is not used in the math expressions for any def or path parameters.
usecv: This is a def parameter which uses the characteristic value (cv). This is not yet allowed for def parameters.
useundef: The math expression for this GDS parameter uses an undefined parameter name.
binary + $token: The math expression for this GDS parameter contains an unallowed binary math operator, $token.
function + $token: The math expression for this GDS parameter contains a mathematical function unknown to Ifeffit, $token.
notunique: The name of this GDS parameter is not unique.
parens: The math expression for this GDS parameter has unmatched parentheses.
progvar: The name of this GDS parameter is an Ifeffit program variable name.
badchar: The name of this GDS parameter contains an unallowed character. Allowed characters are letters (a-z), numbers (0-9), and underscore (_). The first character must not be a number.
merge: This is an parameter which has been defined twice, possibly from the merge of fitting projects or the creation of two more similar quick first shell fitting models.

Problems with Fit objects

gds: No GDS parameters are defined for this fit
data: No data sets are defined for this fit
paths: No paths are defined for this fit
nvarnidp: This fitting model uses more guess parameters than the available information content of the data.
nvarys: This fitting model uses more than Ifeffit's compiled-in limit of guess parameters (&max_varys).
nparams: This fitting model uses more than Ifeffit's compiled-in limit of parameters (&max_scalars).
nrestraints: This fitting model uses more than Ifeffit's compiled-in limit of restraints (10).
ndatasets: This fitting model uses more than Ifeffit's compiled-in limit of data sets (&max_data_sets).
npaths: This fitting model uses more than Ifeffit's compiled-in limit of paths (&max_paths).
defaultpath: More than one path is flagged as being the default path, making it unclear how to evaluate the log file.
loop + $token: The parameter $token refers to itself in its math expression.
cycle + $token: There is a cyclical dependence among a set of parameter math expressions. This cycle is $token.

CONFIGURATION AND ENVIRONMENT

See Demeter for a description of the configuration system.

BUGS AND LIMITATIONS

Missing tests:

Test that every Path is associated with a data set. (Warn, not fatal.)
Test that each data in the data array is properly defined.
Test that every Path points to a real path file

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.