Previous Next Table of Contents

3. Keywords

Take a peek at the Appendix. Included there are a few examples of input files for Phit. This chapter explains the meanings of all the keywords recognized by Phit.

Phit.inp uses keywords to describe the input parameters. With only a few exceptions, the keywords are allowed to occur in any order in the file, and usually have transparent meanings. This structure allows the input file to be easily read and modified. All keywords use the syntax:

        keyword delimiter value(s) delimiter ...

The delimiter can be:

  1. one or more white spaces (blanks and/or TABs)
  2. one equal sign and any number of white spaces
  3. one comma and any number of white spaces

Most keywords take only one value. Many keywords can be put on one line (though some keywords require their own line). Internal comments can be written anywhere in phit.inp, which help remind you what the keywords mean, or how you chose the input values. Keywords can be in upper, lower, or mixed case. Phit is not sensitive to the case of keywords or their values.

3.1 A Brief List of the Keywords

  1. !, %, # -- characters denoting comments
  2. title -- user supplied title line
  3. comment -- synonymous with title
  4. include -- name of an include file
  5. data -- name of input data file
  6. read -- synonymous with data
  7. infile -- synonymous with data
  8. nkey -- numeric key of input UWXAFS data record
  9. skey -- symbolic key of input UWXAFS data record
  10. outfile -- name of output file
  11. logfile -- name of log file
  12. format -- i/o file format
  13. formin -- input file format
  14. formout -- output file format
  15. write -- output data range
  16. xaxis -- abscissa label in math expressions
  17. sigma -- logical flag for input measurement uncertainty
  18. sigdat -- constant input measurement uncertainty
  19. cormin -- minimum correlation reported in log file
  20. x1 - x10 -- fitting range values
  21. xmin -- minimum fitting range
  22. xmax -- maximum fitting range
  23. npoints -- number of points in nofit output
  24. end -- flag marking end of input file
  25. all -- logical flag for writing out individual functions
  26. residual -- logical flag for writing out array of residuals
  27. nosum -- logical flag for not writing sum of functions
  28. noout -- logical flag for writing no output files
  29. norun -- logical flag for stopping after reading input file and data file
  30. dryrun -- synonymous with norun
  31. nofit -- logical flag for only summing functions
  32. noerr -- logical flag for skipping error analysis
  33. guess -- parameter to vary in fit
  34. set -- parameter set by a math expression
  35. function -- math expression, part of sum in fit
  36. id -- description line for corresponding function

3.2 Full Explanation of Keywords

!, %, and #

These characters denote comments in the input file. Anything on a line following any one of these characters will be ignored unless they follow the keywords title, comment, or id in which case they will be part of the title or id line.

Title or Comment

This is a title line that will be written to the log file and to each output data file. It can be used to describe and document a run of the program. Up to 9 title lines of 72 characters each are allowed.

Include

This is the name of a file that contains additional keywords to be parsed when the input file is read. The include file name can be up to 72 characters long and may contain a directory path. The include file is read according to the same syntax as phit.inp. All keywords read in the include file are handled equivalently to those in phit.inp. The line containing the keyword include is entirely parsed before the include file is opened and read. When the include file is finished, parsing of the input file will continue. Nested include files are allowed although there is a limit to how deeply they may be nested. Include files are never necessary but are allowed as an organizational convenience for complicated input files.

Data, Read, or Infile

This is the name of the input data file. It may be up to 72 characters long and may contain a directory path. The filename should not contain spaces, tabs, commas (,), or equal signs (=). These characters will confuse the parsing algorithm. The abscissa grid provided in the input file is used for writing out the output data. See the full description of the x1 - x10 keywords for a discussion of how a limited fitting range can be chosen. Not providing an input file name is equivalent to setting the nofit flag or to providing no guess values. In this case, Phit will evaluate and sum the functions using the guess and set values as stated in the input file. See the full description of the npoints keyword for a discussion of how the output abscissa grid is chosen if no input data file is provided.

Nkey and Skey

These are the numeric and symbolic keys that identify a record in a UWXAFS data file. See the data format document in the UWXAFS package for more details on this file format. At least one of these two must be specified if the UWXAFS file format is used.

Outfile

This is the name for the file containing the sum of functions. The file names for the individual functions will be the same with the extension replaced with the function number from the input file. If no output file name is specified, the input file name will be used with the extension changed to fit, out, or the function number, as appropriate. The file extension is defined as all characters after the final dot (.) in the file name. This definition meets the definition of an extension in DOS and VMS, and is well defined in a Unix environment.

Logfile

This is the name of the log file. The input parameters, set math expressions, functions and ids, results of the fit, and results of the error analysis will be written to this file. Much of this information will not be written anywhere else, so this is an important file! The default name for this file is phit.log.

Format, Formin, and Formout

These specify the formats for the input and output data files. By default, files are read in the ASCII format. The other option is the UWXAFS format. The format keyword specifies both input and output format. Note that the input and output formats do not need to be the same.

Write

This determines how the output data will be written to the output data files. If this keyword is set to full, the sum of functions and individual functions will be evaluated at each input abscissa value in the input file. If it is set to fit, the functions will only be evaluated at abscissa values within the fitting ranges. This is set to full by default.

Xaxis

This is a character string that will be used to denote the abscissa in all math expressions. By default this is x, but something else might be more appropriate for a specific problem. For instance if the input data is an XAFS spectrum in energy, this might be set to e. If the input data is in temperature, it might be T.

Sigma

If a third column containing measurement uncertainties at each abscissa value is provided in the input file, Phit will use those in calculating chi-square and in the error analysis if this keyword is found in the input file. This keyword does not take any value. Simply placing it somewhere in the input file will toggle this logical flag. If no information about measurement uncertainties is provided in the input file, a single number which is the standard deviation of the residuals of the fit will be used.

Sigdat

To evaluate chi-square using a single, user-chosen number, specify it with this keyword. It will be used to evaluate chi-square and to perform the error analysis. If no information about measurement uncertainties is provided in the input file, a single number which is the standard deviation of the residuals of the fit will be used. This value of sigma will be used to normalize chi-square and the error bars.

Cormin

Part of the error analysis is the computation of correlations between variables. By default, only those variables with more than 15% correlation will be written to the log file. This limit can be changed with this keyword. It takes a value between 0 and 1.

X1 through X10

These values can be used to limit the range of the fit to some subset of the input data range. They take values within the range of the abscissas of the input data and are specified in pairs. Only the input data between x1 and x2 and between x3 and x4 and so on will be included in the fit. The data between x2 and x3 and so on will be excluded from the fit. Chi-square and the error analysis will be computed using only the data contained within these abscissa ranges. By default x1 is the first data point, x2 is the last data point, and the other eight are unused. The values of these keywords will be sorted on input and if an odd number of values are found, the last data point will be inserted into the list. When functions are evaluated with the fitting results and written to the output data files, they can either be evaluated in the fitting range as specified by these keywords or in the range of the input data. This is determined by the keyword write.

Xmin and Xmax

These are synonymous with X1 and X10. When only the ends of the input data range are being excluded, these keywords are perhaps more mnemonic.

Npoints

This keyword is only used in the situation where functions are evaluated without performing any fit. If no input data is specified, then Phit needs some way to determine an abscissa grid over which to evaluate the functions. In this situation, Phit will make an even grid containing npoints points between xmin and xmax and evaluate the function on that grid. If an input data file is specified and no fit is called for, the Phit will use the abscissa grid between xmin and xmax from that data file and ignore the value of npoints. By default, npoints is 100.

End

When this keyword is encountered in the input file, Phit will stop reading the input file and begin the fit. Everything after this keyword in the input file will be ignored. This keyword takes no value.

All

This is a logical flag telling Phit to write out each individual function. This keyword takes no value, simply writing it to the input file will toggle this logical flag.

Residuals

This is a logical flag telling Phit to write out an array containing the residual at each data point written to the output file. If the value of the keyword write is fit and the output files only contain the function evaluations at the data points used in the fit, then the residual file will contain the residual used in evaluating chi-square. If write is set to full, then the residual file will contain the difference between the function evaluations and the data at every data point in the input data file and is not the residual array used to evaluate chi-square. This keyword takes no value, simply writing it to the input file will toggle this logical flag.

Nosum

This is a logical flag telling Phit not to write out the sum of functions. This keyword takes no value, simply writing it to the input file will toggle this logical flag.

Noerr

This is a logical flag telling Phit not to perform any error analysis. This keyword takes no value, simply writing it to the input file will toggle this logical flag.

Noout

This is a logical flag telling Phit to write out neither the sum of functions nor the individual functions. This keyword takes no value, simply writing it to the input file will toggle this logical flag.

Norun or Dryrun

This is a logical flag telling Phit to stop after reading the input data file. The input file and the data file will be read and all math expressions will be interpreted before stopping. This option is useful for ``spell checking'' your input file. This keyword takes no value, simply writing it to the input file will toggle this logical flag.

Nofit

This is a logical flag telling Phit to not perform a fit. Instead the functions and set values will be evaluated at the initial guess values specified in the input file and will be written to output files. This keyword takes no value, simply writing it to the input file will toggle this logical flag.

Guess

This keyword takes two values and must be placed on its own line. The first value is the label that will be used in your math expressions and the second value is the initial guess of this parameter. The label is a character string of up to 20 characters and the initial guess is a number. Up to 50 guess values can be specified. It is prudent to choose an initial guess that is somewhat close to what you expect for the best fit value. For some line shapes, a poor initial guess can confound the minimization algorithm resulting either in an inability to minimize chi square or in the location of a false minimum of the parameter set. See chapter 5 for more discussion of appropriate initial guesses. Setting no guess values is equivalent to setting the nofit flag.

Set

This keyword takes two values and must be placed on its own line. The first value is a label that will be used to identify this value in other math expressions. The second value is a math expression which will be evaluated and whose value will be assigned to its label for use in evaluating other math expressions. The label is a character string of up to 20 characters. The math expression is a character string of up to 74 characters. Up to 300 set values can be specified. The set value must be contained on one line. Phit will not read a math expression that stretches over more than one line. If a math expression is very long, it would be prudent to break it up into smaller ones. See Chapter 5 for more discussion of writing good math expressions.

Function

This keyword takes two values and must be placed on its own line. The first value is an integer which is the index identifying the function. The second is a math expression which will be evaluated as part of the sum of functions to fit to the data. This is a character string of up to 74 characters. Up to 20 functions can be specified. The function must be contained on one line -- Phit will not read a math expression that stretches over more than one line. If the math expression is very long, it would be prudent to write it in terms of several set values. See chapter 5 for more discussion of writing good math expressions.

Id

This keyword takes two values and must be placed on its own line. The first values is an integer which is the index of the function associated with this id line. The second value is a character string of up to 74 characters. This is a comment line specifically associated with a particular function. It will be written to individual function data file, if that output is requested, and it will be written along with its function in the log file. Id lines with an integer index shared by no functions will be ignored.


Previous Next Table of Contents