Go to the first, previous, next, last section, table of contents.


The syntax and appearance of input files

The syntax of FEFF and the UWXAFS programs

Each of FEFF and the UWXAFS programs requires an input file as part of its input structure. This input file is always an ASCII text file which contains all of the information required by the program at run-time. This information might include the names and locations of any other input files, the names to be assigned to output files, and any physical or run-time parameters required by the program.

Although there are some differences in how each program interprets its input file, there are several common rules governing the syntactic structure of the input files. The input files are always parsed. This means that there is considerable freedom in the order in which information is placed in the input file. Each program reads a line of input and searches for specially recognized words called keywords. When a recognized keyword is found, the next one or more words in the input file are read and interpreted in a context appropriate to the keyword. For example, in AUTOBK the word `data' is used to specify the name of the file containing the input chi(k) data. When AUTOBK encounters the word `data' it interprets the following word as the name of a computer file.

In all of the programs keywords and their values are separated by white space. The formal definition of white space in all of the programs is any number of space or tab characters followed by zero or one comma or equals sign followed by any number of spaces or tabs.(4) Here is an example of how this rule might be implemented:

	keyword1 = value1	keyword2 = value2

In this example, the equals sign (`=') is used to emphasize the relationship between the keyword and its value, and a tab is inserted before the second keyword.

In most cases there can be any number of keyword/value pairs on a line and the keywords can come in any order. There are a few notable exceptions to this rule:

  1. In FEFF there can only be one keyword per line and it must come at the beginning of the line. Anything on a line after the keyword and its value is ignored by FEFF.
  2. In ATOMS the keyword `atoms' (or possibly `basis') must be the last keyword in the file.
  3. In ATOMS the 10 characters following the keyword `space' are read as the value of that keyword. This is because space group notation contains spaces, but no space group symbol is longer than 10 characters.
  4. In FEFFIT all path parameters and the words `set', `guess', and `local' must be the only keywords on their lines and must come at the beginning of the line.
  5. In FEFFIT there is one keyword that contains white space. It is `next data set' and is used to denote the boundary between data sets.

For complete details on the keywords recognized by these programs and the syntax of their values, see the documents for each program.

Each of the programs recognizes certain characters as comment characters. This means that any text on a line following one of these characters will be ignored by the program. In FEFF `*' is the comment character. In ATOMS and AUTOBK any of `*', `#', `%', or `!' are comment characters. In FEFFIT all of `*', `#', `%', or `!' are beginning of line comment characters, while `#', `%', or `!' are comment characters in the middle of the line. The reason for this distinction in FEFFIT is that `*' is used in math expressions.

Additional syntax rules imposed by FUSE

The syntax rules described above are an integral part of @fuse{} and are used to determine the behavior of most of its features. There is a major syntactic rule imposed by @fuse{} for FEFFIT input that is not a requirement of the program. This rule is:

All path parameters sharing a common path index (i.e. all those referring to the same scattering path as calculated by FEFF) must be contiguous in the input file. Such a grouping of path parameters is called a path paragraph. The first line in a path paragraph must be for the path parameter `path', which is used to identify the name of the FEFF output file containing the calculation for that scattering path. Path paragraphs are separated by lines containing only comment and whitespace characters (i.e. space, tab, comma, =, *, #, %, and !).

This definition of the path paragraph is required for several of the most powerful editing features in FEFFIT minor mode. I strongly encourage you to observe the syntactic structure of the path paragraph. If you prefer to group together all `path' lines separately from all `sigma2' lines, then you will not find FEFFIT minor mode to be particularly helpful. Sorry.

Syntax colorization

Each minor mode has rules for syntax colorization of the text. @fuse{} supports both font-lock and hilit19 for syntax colorization. Keywords are cast in one of several colors, with conceptually similar keywords sharing colors. Comments are set in a different color, which is red by default. See the installation instructions for how to enable your Emacs session to use @fuse{}'s syntax colorization.

If you already use either font-lock or hilit19, then @fuse{} will display your input files with syntax colorization. If you would like to start using syntax colorization, the set up is easy. To enable syntax coloring of the text of your input files using font-lock, place the following line in your `.emacs' file:

     (global-font-lock-mode t)

To enable syntax coloring of the text of your input files using the hilit19 package, place the following lines in your `.emacs' file:

     (cond (window-system
            (setq hilit-mode-enable-list  '(not text-mode)
                   hilit-background-mode   'light
                   hilit-inhibit-hooks     nil
                   hilit-inhibit-rebinding nil)
            (require 'hilit19) ))

I find that font-lock offers better performance than `hilit19'. Both packages are supported by @fuse{}, although hilit19 is no longer supported by its author.

Associating programs with input files

Each of the programs requires that the input file have a particular name. For example FEFF requires that its input file be called `feff.inp'. You might, however, wish to use file names which are mnemonically associated with the contents of the file. For instance, the `feff.inp' file used to model data on metallic copper might be called `cu-feff.inp'. Because @fuse{} uses minor modes specific to each program for editing the input files, it is necessary for @fuse{} to determine which for which program each edited input file is intended. To determine this, it first looks at the file name, if the filename is obviously indicative of a particular program (e.g. `autobk.inp' is almost certainly intended for use with AUTOBK) then that program is used. If the filename is not obviously indicative, then @fuse{} may prompt you for a program name when you edit the file for the first time. It is important to answer this question correctly. Every input file is edited in INPUT major mode and in a minor mode appropriate to the program. To enable the full functionality of @fuse{}, the associated program must be identified so that the appropriate minor mode can be used.

Automatic configuration

There are several features in @fuse{} that are routinely set in the course of editing an input files that are convenient to retain between editing sessions. To do this, @fuse{} writes special comment lines to your input files that are read when the file is initially loaded by Emacs and used to set variables which appropriately alter the behavior of @fuse{}. The comment lines are generally written to the end of the input file and begin with a special string of comment characters. They look something like this:

!!&& Local Variables:
!!&& input-program-name: "autobk"
!!&& End:

There are several variables which are set in this manner. The most important is the one that identifies the program for which the input file is intended. In the example above, the comment line identifies AUTOBK as the program for the input file.

There are currently five other pieces of information that are stored in these special comment lines. These are (1) the directory path to the location of files from a FEFF run, (2) the directory path to input data files, (3) the directory path to out files, (4) the default k-weight to use when chi(k) data is plotted, and (5) the name of the master file for an include file in a multi-file input file. In the future more automatic configuration possibilities may be added. @fuse{} will ignore any other variable values in the list when it updates it's own automatically configured variables.

The automatic configuration lines are updated each time an input file is saved to disk. Each of the variable set by these lines can be altered by functions built into @fuse{} during the course of editing. These are found in the `Input' menu and described in the quick reference card. One of the variables in @fuse{}, `input-prohibit-autoconfig-flag', can be set to prohibit the writing of the auto-configuration lines. Use this if you object to having @fuse{} insert text into your input file. I recommend, though, that you allow it to do so. It is very convenient to not have to re-enter this information every time the file is edited.

Keywords and keyword parsing

One of the difficulties of using FEFF and the UWXAFS programs is remembering the names of the keywords recognized by the various programs and what values each of the keywords takes. @fuse{} can help you. It has knowledge of all keywords used by each of the programs hardwired in and offers several functions to let you use that knowledge.

Templates
Each minor mode offers template functions which insert necessary keywords into your input file with blank spaces for you to fill in appropriate values. Using the templates assures that your input file will at least run the program to completion without neglecting any crucial information. The templates are described in more details in the chapters on the minor modes. All of the templates in @fuse{} are made using the `tempo' package. This means that each place where a value needs to be inserted by the user is a hotspot. The hotspots are marked by salmon colored rectangles. Once the hotspots are filled in you can clear the salmon colored rectangles with C-c C-t c. The functions `tempo-forward-mark' and `tempo-backward-mark', bound in @fuse{} to M-n and M-p, can be used to move among the hotspots.
Keyword completion
The function `input-complete-keyword' (normally bound to M-tab) will attempt to complete a partially typed keyword. If the string already typed matches only one possible keyword, that keyword will be completed, colored according to syntax, and a brief explanation of the keyword will be offered in the echo area. If the typed string does not match any keyword, you will be told in the echo area. If more than one keyword is matched, all possible matches will be offered in the echo area. As an example, when editing a FEFFIT input file, if you type g then M-tab, `guess' will be inserted into your input file and you will told in the echo area that `guess' is used to set the name and initial value of a fitting parameter.
Argument descriptions
The function `input-arg-for-this-keyword' (normally bound to M-?) will offer a brief description of the keyword underneath the cursor along with a description of the sort of argument it takes. The is written to the echo area.
Verification of keyword values
The function `input-check-this-keyword-arg' (normally bound to M-ret) will perform a simple check of the value of the keyword underneath the cursor. For example, if the keyword is supposed to take a numeric value, this function will check to see that the value is a number. If the keyword specifies an input data file, it will check to see that the value is the name of a readable file.
Verification of input files
This functionality is not yet a part of @fuse{}, @emph{but in a future version a function will exist to verify an entire input file by repeatedly using
`input-check-this-keyword-arg'. If any mistakes are found, error messages will be written to a second window. I plan to provide a simple way of jumping from messages in the error window to the appropriate point in the input file.}
Display of all possible keywords
The function `input-display-keywords' (normally bound to C-c C-b k) opens a second window and displays all possible keywords for the program associated with the input file. The keywords are tabulated along with brief descriptions.

Indentation and separation

In the first section of this chapter I described the rules recognized by the programs for separating keywords and values. As long as at least one whitespace character separates words in the input files, the programs are quite content. Merely meeting the minimum requirement, however, will make for a messy looking and hard to read input file. Because you or some other human will eventually read your input file, it is convenient to adopt certain conventions about indenting text and about separating textual elements within the input files.

To make input files easier to read thus easier to understand, @fuse{} uses several configurable rules for determining proper indentation and separation. The choices @fuse{} makes about indentation and separation are context-dependent. That is, the indentation of, say, a line containing a `guess'ed variable in FEFFIT may be different from the indentation of a line in an AUTOBK input file. Variables in @fuse{} with names ending in either `indent' or `separate' control the amount and type of whitespace used in various situation by many @fuse{} functions.

Each of these variables takes an integer value. A positive integer specific how many spaces will be inserted as indentation or separation. A negative number specifies the number of tabs to insert. For indentation variables, a value of 0 means that no whitespace will be inserted, i.e. the text will be flush against the left side of the screen. For separation variables, a value of 0 will default to -1, i.e. a single tab character. While you are certainly free to choose absurdly large numbers, for example -73 for an indentation value, I strongly recommend against this. For one thing, an indentation of 73 tabs will be ugly and difficult to read. For another, each of the programs has a hard-wired limit on the length of a text line. For example, ATOMS only reads the first 78 characters of each line.

Each minor mode has a `cleaning' function which can be used to standardize the appearance of the file. Each cleaning function will alter each line in the file by deleting all existing indentation and separation on the line and inserting the appropriate whitespace as determined from the user configuration variables. All of the variables have defaults that will make any input file tidy and easy to read. The default values for variables used by the FEFF minor mode are chosen to make the file look like one generated by ATOMS.

Several other functions, such as those that insert templates, also use the indentation and separation variables.

Master files and include files

FEFFIT, AUTOBK, and PHIT allow the use of include files. @fuse{} allows you to specify the relationship between include files and their master files by setting an automatic configuration variable. Currently this variable is used only by a few functions. The program running function will use the master file as the input file. Also the functions for jumping to log and prm files jump to the files appropriate to the master file. Plotting and paragraph manipulation functions do not currently use the master file.


Go to the first, previous, next, last section, table of contents.