Structure of the Input¶

Keywords¶

Input for ADF is structured by keywords, in short: keys. A key is a string of characters that does not contain a delimiter (blank, comma or equal sign). Keys are not case sensitive. Input is read until either the end-of-file condition (eof) becomes true, or until a record end input is encountered, whichever comes first. (end input is not a key.)

Key-controlled input occurs with two formats. In the first you have only one record, which contains both the key and - depending on the case - associated data: the key argument:

KEY argument

The whole part of the line that follows after the key is the argument. It may consist of more than one item.

The alternative format is a sequence of records, collectively denoted as a key block. The first record of the block gives the key (which may have an argument). The block is closed by a record containing (only) the word end. The other records in the block constitute the data block, and provide information related to the key.

KEY {argument}
   data record
   data record
   (etc.)...
   ...
end

In this manual, when items are optional, such as the argument in the scheme above, they are typed enclosed in curly brackets {}. The { and } characters themselves are not part of the item. Different allowed / eligible values are separated by a bar (|). The keywords are usually typed in small capitals, subkeys in italic small capitals.

Structures like ‘key=value’ should be read as: type ‘key=’ as such, followed by a suitable value.

Block type keys may have subkeys in their data block. The subkeys may themselves also be block type keys. The data blocks of block type subkeys, however, do not end with end, but with subend:

KEY {argument}
 data
 data
 subkey {argument}
    subkey data
    subkey data
    ...
 subend
 data
 data
 ...
end

Layout features such as an open line, indentation, or the number of spaces between items are not significant.

The format to be used for a key is not optional: each admissible key corresponds to one specific format. As a general rule, the block keys control lists of data, such as atomic position coordinates.

A few special keys can have either format. For such keys the format actually in effect depends on the presence of the argument: the block type applies in absence of the argument. The block type applies also when an argument is present that ends with a continuation symbol. The continuation symbol is the ampersand (&) or, alternatively, two contiguous plus-characters preceded by at least one blank (++):

KEY {argument} &
   data
   data
end

The various types of keys are referred to respectively as simple keys, block keys, and general keys.

A considerable number of keys can be used to specify the geometry, the model Hamiltonian, cf. the Density Functional, the precision of the calculation, and so on. The order in which keys occur in the input file is immaterial, except that a few special keys determine how input data is interpreted, such as the unit-of-length for atomic coordinates. These interpretation keys must be used before the pertaining data in input occur. This will be mentioned explicitly again where they are discussed.

The items that can be addressed with keys and the keys themselves are listed in the Index.****

Irrelevant keys, misspelling of keys

Specification of a key that is not relevant in the calculation will go unnoticed. Similarly, if you misspell a key such that it is not recognized, the incorrectly labeled input data will be ignored and the program will proceed as if the intended key had not occurred. This results in the application of pre-defined default values or in an error abort, depending on the case. Therefore, whenever the output suggest that part of your input has been ignored, check the spelling.

In this context we stress again: be alert on TAB characters: don’t use them at all.

ADF may recognize a key if it is spelled incompletely, that is, if only some initial substring is given, and also if redundant characters are typed after the end of the key. The reason is that often only a small initial part of the true keyname is checked against the input items. Don’t rely on this, however: it is not formally supported and it may get disabled in a next release without further notice.

We advise therefore to stick to the correct key names. In particular, you must avoid to use different abbreviated or elongated forms when a key occurs more than once in input: ADF will likely assume that you want to indicate distinct keys and it will associate only one of them with the key you had in mind.

Units of length and angle¶

Geometric lengths and angles are in units defined by:

UNITS
   length Angstrom / Bohr
   angle Degree / Radian
End

Angstrom and Bohr, respectively Degree and Radian, are recognized strings. Each of the subkeys is optional, as is the key UNITS itself. Defaults: Angstrom for lengths, and Degree for angles.

The position of the key UNITS in input is significant as regards the evaluation of expressions (see the paragraph on constants and functions below). In other respects its position plays no role. To avoid mistakes one should place units as early as possible in input (if at all).

Interpretation of Input¶

Expressions

ADF supports the use of arithmetic expressions, functions, and constants to represent numerical data. This can be convenient for the input of, for instance, atomic positions when these would most easily be represented in terms of 1/3, sin(360/5), et cetera. Using expressions and functions is easier, avoids the tedious typing of long decimal expansions and solves the question of precision (how many digits should be supplied?).

The standard arithmetic operands in Fortran (+ - * / **) can be applied in expressions, together with parentheses where suitable.

Blanks are allowed and ignored, but they are interpreted as separators, i.e. as denoting the end of an expression, whenever the part until the blank can be evaluated as a correct expression. For instance 3* 4 will be interpreted as 12, but 3 *4 will be interpreted as 3, followed by a character *, followed in turn by the number 4.

All numbers and results are interpreted and handled as being of type real, but whenever the result is a whole number (allowing for very small round-off) it will be recognized and accepted as an integer when such data is required.

Constants and functions

The user may define constants and functions in the input file, and apply them subsequently in expressions. The input file is read sequentially and constants and functions must be defined before they can be used.

The argument list of a function must be enclosed in parentheses and the arguments, if more than one, separated by commas.

The following functions are predefined in ADF and can be used directly in input:

sin, cos, tan, asin, acos, atan, exp, log, sqrt, nint. Each of them has one argument. log is the natural logarithm (base e).

No constants are predefined.

The angular argument to the trigonometric functions cos, sin, tan is in the unit for angles as defined by units, provided the unit has been set before it is applied. For the result of the inverse trigonometric functions the same holds.

Constants and functions can be defined with the block key DEFINE:

DEFINE
   angle=54
   ab = sin(angle/3)
   s13 = 14*sqrt(2)
   func(x,y,z) = x*ab+y**2-y*z
end

The constants angle, ab, and s13 are defined together with a function func, using the predefined functions sin and sqrt. These can then be applied to assign values elsewhere in input.

In the example above, the constant angle is used in the definition of ab, and ab is used in turn to define func; these constructions are allowed because angle is defined before ab, and ab is defined before func.

The replacement of constants, functions, and other expressions by their numerical values may considerably increase the length of the input record, in particular when real values are being generated (by the parser) in the standard format E22.14. Take care that the resulting record does not exceed 80 characters. The program will abort or may run into an error if this is violated.

The input-reading routine applies the constants and functions wherever it is allowed to do so. To prevent any unwanted replacements in the input file you should avoid very short identifiers for constants and functions.

Warning example:

DEFINE
   A=3.18
   C=4.12
end
...
atoms
   C 0.00 1.05 -3.22
...

The program will apply the definition of the variable C and read:

DEFINE
   A=3.18
   C=4.12
end
...
atoms
   4.12 0.00 1.05 -3.22
...

Avoid single-character identifiers!

Strings

Quotes can be used to designate strings, i.e. (parts of) records which are not to be parsed for expressions, but which should be taken as they are. The quotes themselves are ignored, i.e. removed by the parser. Two consecutive quotes inside a string are interpreted to denote the (single) quote character as a part of the string.

Where does parsing apply?

Replacing pre-defined variables and expressions by their value is applied only to keys that carry numerical data. For example: atoms, define, units. However, it is not applied to keys that carry electronic occupation numbers.

Note that when parsing applies to a given key the whole record of the key (key + argument) and its data block are parsed. The parsing then applies to all items, even those that in themselves have no numerical meaning (for instance, the atom type names in the atoms data block are scanned and must of course then not be ‘defined’ as identifiers with a numerical value.

Constants vs. geometric parameters

Note carefully the difference between constants defined with define and identifiers that are used for atomic coordinates in the data blocks of atoms and geovar. Constants defined under define are merely symbols for, and exactly equivalent to, certain numerical values, whereas the coordinate identifiers carry implications such as the distinction between frozen and optimization coordinates. Constants affect only the input after their definition and the location of their definition in the input file is significant. Geometric identifiers only relate to the data blocks of atoms and geovar respectively and the relative order in which the keys atoms and geovar occur is irrelevant.

Including an external file¶

You can include an external ASCII file in the input with the INLINE key:

INLINE FileName

The file name should include the path, either absolute or relative to the run-directory. The content of the file FileName is included in the input at the point where the INLINE key occurs (the INLINE key may occur any number of times in the input).

The INLINE feature makes it easy to pack your preferred settings in one file and use them in every run with minimum input-typing effort, or can be used to include files containing the atomic coordinates.

Title, comment, layout of input¶

TITLE Title

Title may be any string. The program combines it (that is, the first approximately 50 characters) with date and time of the job to construct the* job identification.* The job identification is used to stamp an identification on result files, which will be read and printed if such a file is used again, for instance as a fragment file.

The job identification will also be echoed in the output header to identify the current run. By default the date and time are combined with a dummy string. In Create mode the title is first read from the data file that supplies the basis functions etc and can then be overwritten via input.

Note that, contrary to some other programs, ADF does not take the first input record as a title. Typing your title as the first record, without starting the record with the keyword title, may produce very strange results: ADF will try to interpret the first word on that line as a keyword, possibly abbreviated!

You can put more remarks in the input file to be echoed in the standard output file; these will not become part of the job identification:

COMMENT
   text
   ...
end

The text records are copied to the output header, directly after the job identification. Expressions are not parsed and constants or functions are not replaced: it is a straightforward copy.

The key COMMENT may occur any number of times; all text blocks are printed in the output header with a blank line between any two text blocks.

Empty records and leading blanks in records are allowed and ignored, and can be used to enhance clarity and readability of the input file for human readers.

An exclamation mark (!) is interpreted by the input reading routine as denoting the end-of-line. Instead of the exclamation mark you may also use a double colon (::). The part of the line after the exclamation mark (double colon) - including the ! or :: itself - is ignored. In this way one can include comments and clarifying remarks, which will not be echoed in the output header (compare the key COMMENT).