Input

The input options for ADF are specified in a text file consisting of a series of key-value pairs, possibly nested in blocks. Much of the general remarks about input for ADF apply also to related property and analysis programs, which are also described in this document. The input for the description of the system, structure and reactivity, vibrational spectroscopy, belongs (mostly) to the AMS driver part of the input.

The input is usually embedded in an executable shell script. This is the content of a typical shell script for running a ADF calculation:

#!/bin/sh

$AMSBIN/ams <<eor
   # This is the beginning of the input.
   # The input consists of key-value pairs and blocks.
   # Here we define the input option for the AMS driver:

   Task GeometryOptimization

   System
      Atoms
         H 0.0 0.0 0.0
         H 0.9 0.0 0.0
      End
   End

   # Next comes the ADF "Engine" block. The input options for ADF, which are
   # described in this manual, should be specified in this block:

   Engine ADF
      Basis
         Type DZP
      End

      XC
         GGA PBE
      End
   EndEngine
eor

To run the calculation above from command-line you should:

  1. Create a text file called, for example, test.run and copy-paste the content of the script above

  2. Make the script executable by typing in your shell chmod u+x test.run

  3. Execute the script and redirect the output to a file: ./test.run > out

The program will create a directory called ams.results. Inside it, you will find the logfile ams.log (which can be used to monitor the progress of the calculation) and the binary results files ams.rkf and adf.rkf. After the calculation is completed, you can examine the output file out. For more details, see

See also

The Examples section contains a large number of input examples.

Important

Most options described in this manual should be specified in the ADF Engine block:

# All ADF keywords should be specified inside the 'Engine ADF' block
Engine ADF
   Basis
      Type DZP
   End

   XC
      GGA PBE
   End
EndEngine

General remarks on input structure and parsing

  • Most keys are optionals. Defaults values will be used for keys that are not specified in the input

  • Keys/blocks can either be unique (i.e. they can appear in the input only once) or non-unique. (i.e. they can appear multiple times in the input)

  • The order in which keys or blocks are specified in the input does not matter. Possible exceptions to this rule are a) the content of non-standard blocks b) some non-unique keys/blocks)

  • Comments in the input file start with one of the following characters: #, !, :::

    # this is a comment
    ! this is also a comment
    :: yet another comment
    
  • Empty lines are ignored

  • The input parsing is case insensitive (except for string values):

    # this:
    UseSymmetry false
    # is equivalent to this:
    USESYMMETRY FALSE
    
  • Indentation does not matter and multiple spaces are treaded as a single space (except for string values):

    # this:
         UseSymmetry     false
    # is equivalent to this:
    UseSymmetry false
    
  • Environment variables in the input will be replaced by their value. We only support simple substitution of variables (optionally surrounded by {}). All other parameter expansion features of the POSIX shell (e.g. default values) are not supported. Expansion of a variable can be prevented by prefixing the leading dollar ($) with a backslash (\). Note that variables which are not set will expand to an empty string, just like in a shell:

    File $SOME_DIRECTORY/file.txt
    File ${SOME_DIRECTORY}_BACKUP/file.txt
    Key  \$WILL_NOT_EXPAND
    

Keys

Key-value pairs have the following structure:

KeyName Value

Possible types of keys:

bool key

The value is a single Boolean (logical) value. The value can be True (equivalently Yes) or False (equivalently No.). Not specifying any value is equivalent to specifying True. Example:

KeyName Yes
integer key

The value is a single integer number. Example:

KeyName 3
float key

The value is a single float number. For scientific notation, the E-notation is used (e.g. \(-2.5 \times 10^{-3}\) can be expressed as -2.5E-3). The decimal separator should be a dot (.), and not a comma (,). Example:

KeyName -2.5E-3

Note that fractions (of integers) can also be used:

KeyName 1/3    (equivalent to: 0.33333333333...)
string key

The value is a string, which can include white spaces. Only ASCII characters are allowed. Example:

KeyName Lorem ipsum dolor sit amet
multiple_choice key

The value should be a single word among the list options for that key (the options are listed in the documentation of the key). Example:

KeyName SomeOption
integer_list key

The value is list of integer numbers. Example:

KeyName 1 6 0 9 -10

Note that one can also specify ranges of integers by specifying the interval and (optionally) the step size separated by colons:

KeyName 1:5       (equivalent to: 1 2 3 4 5)
KeyName 2:10:2    (equivalent to: 2 4 6 8 10)
KeyName 20:10:-2  (equivalent to: 20 18 16 14 12 10)

Note also that ranges can be freely combined with individual numbers:

KeyName 1:5 10 20  (equivalent to: 1 2 3 4 5 10 20)
float_list key

The value is list of float numbers. The convention for float numbers is the same as for Float keys. Example:

KeyName 0.1 1.0E-2 1.3

Float lists can also be specified as a range with equidistant points, by specifying the interval’s boundaries (inclusive) as well as the number of desired subintervals separated by colons:

KeyName 1.0:1.5:5  (equivalent to: 1.0 1.1 1.2 1.3 1.4 1.5)

Range specifications can be freely combined with each other and single numbers:

KeyName 0.0 1.0:1.5:5 2.0:3.0:10

Blocks

Blocks give a hierarchical structure to the input, grouping together related keys (and possibly sub-blocks). In the input, blocks generally span multiple lines, and have the following structure:

BlockName
   KeyName1 value1
   KeyName2 value2
   ...
End

Headers

For some blocks it is possible (or necessary) to specify a header next to the block name:

BlockName someHeader
   KeyName1 value1
   KeyName2 value2
   ...
End

Compact notation

It is possible to specify multiple key-value pairs of a block on a single line using the following notation:

# This:
BlockName KeyName1=value1 KeyName2=value2

# is equivalent to this:
BlockName
   KeyName1 value1
   KeyName2 value2
End

Notes on compact notation:

  • The compact notation cannot be used for blocks with headers.

  • Spaces (blanks) between the key, the equal sign and the value are ignored. However, if a value itself needs to contain spaces (e.g. because it is a list, or a number followed by a unit), the entire value must be put in either single or double quotes:

    # This is OK:
    BlockName Key1=value Key2 = "5.6 [eV]" Key3='5 7 3 2'
    # ... and equivalent to:
    BlockName
       Key1  value
       Key2  5.6 [eV]
       Key3  5 7 3 2
    End
    
    # This is NOT OK:
    BlockName Key1=value Key2 = 5.6 [eV] Key3=5 7 3 2
    

Non-standard Blocks

A special type of block is the non-standard block. These blocks are used for parts of the input that do not follow the usual key-value paradigm.

A notable example of a non-standard block is the Atoms block (in which the atomic coordinates and atom types are defined).

Including an external file

You can include an external ASCII file in the input with the @include directive:

@include FileName.in
@include "file name with spaces.in"

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

The @include feature makes it easy to pack your preferred settings in one file and use them in every run with minimum input-typing effort.

Units

Some keys have a default unit associated (not all keys have units). For such keys, the default unit is mentioned in the key documentation. One can specify a different unit within square brackets at the end of the line:

KeyName value [unit]

For example, assuming the key EnergyThreshold has as default unit Hartree, then the following definitions are equivalent:

# Use defaults unit:
EnergyThreshold 1.0

# use eV as unit:
EnergyThreshold 27.211 [eV]

# use kcal/mol as unit:
EnergyThreshold 627.5 [kcal/mol]

# Hartree is the atomic unit of energy:
EnergyThreshold 1.0 [Hartree]

Available units:

  • Energy: Hartree, Joule, eV, kJ/mol, kcal/mol, cm1, MHz

  • Forces: Hartree/Bohr, eV/Bohr, Hartree/Angstrom, eV/Angstrom, kcal/mol/Angstrom, kJ/mol/Angstrom

  • Length: Bohr, Angstrom, meter

  • Angles: radian, degree

  • Mass: el, proton, atomic, kg

  • Pressure: atm, Pascal, GPa, a.u., bar, kbar

  • Electric field: V/Angstrom, V/meter, a.u.

Title, comment

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.

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.

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.

Amsification of ADF in ADF2020

The standalone program ‘adf’ does not exist anymore in ADF2020. The job of AMS driver is to handle all changes in the geometry, e.g. during a geometry optimization, using so-called engines like ADF for the calculation of energies and forces. Details of this change can be found in the section on the

Input parsing changes in ADF2018 and later

The input file parsing for ADF and its properties programs has changed from the 2017 to the 2018 version.

New syntax for a few keywords

In order to adapt ADF to the new (more strict) input format, the syntax of a few keywords had to be changed. The following table contains the list of keywords that have changed in ADF2018. Note that some keywords changed in AMS2020 again, see the section on ADF amsification. Note also that the block key DEFINE was removed.

key in ADF2017 and before

key in ADF2018 and later / comments

CorePotentials

CorePotentials is now a block (and not an general key/block)

Define

removed

Dependency

Dependency is now a block (and not a key)

EField

ADF2020: key ‘System%ElectroStaticEmbedding’ in AMS driver

ETSNOCV

ETSNOCV is now a block (and not a key)

Excitations -> Davidson

Excitations -> Davidson is now a block (and not a key)

Excitations -> Exact

Excitations -> Exact is now a block (and not a key)

Geometry

ADF2020: key ‘Task’ and key ‘Properties’ in AMS driver

Integration Value

Integration -> Accint Value

LinearScaling

LinearScaling is now a block (and not an general key/block)

ModifyStartPotential

ModifyStartPotential is now a block (and not an general key/block)

Occupations

Split into Occupations and IrrepOccupations

Relativistic

ADF2020: block key Relativity

Restart -> Value

Restart -> File -> Value

Response -> Units

Removed optional units for FrqBeg and FrqEnd in Response block

SCF -> ADIIS

SCF -> ADIIS is now a block (and not a key)

SCF -> ARH

SCF -> ARH is now a block (and not a key)

SCF -> DIIS

SCF -> DIIS is now a block (and not a key)

SlaterDeterminants

SlaterDeterminants is now a block (and not an general key/block)

SOPert

SOPert is now a block (and not a key)

Thermo

ADF2020: key ‘Thermo’ in AMS driver

Strict parsing of input file

In ADF2018 and later exact keyword matching is used, meaning that keywords abbreviations (or extensions) are not allowed. In ADF2017 (and previous versions) the parsing of the input file was tolerant and it would allow for abbreviations and extension of keywords.

In the example below, only the first version is allowed in ADF2018 and later, while the second and third version will trigger an input syntax error:

# This is the proper input syntax:
SCF
   Converge 1.0E-7
End

# In ADF2017 you could (for some keywords) use abbreviations. e.g.:
SCF
   Conv 1.0E-7
End

# or extensions. e.g.:
SCF
   Convergence 1.0E-7
End

# Keywords abbreviations and extensions are NOT ALLOWED in ADF2018 and later.

Execution

See