Input¶

The input options for Band are specified in a text file consisting of a series of key-value pairs, possibly nested in blocks. The input is usually embedded in an executable shell script. This is the content of a typical shell script for running a Band calculation:

#!/bin/sh

$ADFBIN/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 Band "Engine" block. The input options for Band, which are
   # described in this manual, should be specified in this block:

   Engine Band
      Basis
         Type DZP
      End

      XC
         GGA PBE
      End
   EndEngine
eor

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

Create a text file called, for example, test.run and copy-paste the content of the script above
Make the script executable by typing in your shell chmod u+x test.run
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 band.rkf. After the calculation is completed, you can examine the output file out. For more details, see the AMS documentation.

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
```

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

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

float_list key

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

KeywordName 0.1 1.0E-2 1.3

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:

Spaces (blanks) between the key, the equal sign and the value are not allowed:

# This is OK:
BlockName KeyName1=value1 KeyName2=value2

# This is NOT OK:
BlockName KeyName1 = value1 KeyName2= value2

The compact notation can be used only for following types of keys: bool, integer, float and multiple_choice. It should not be used for sting, integer_list and float_list keys
The compact notation cannot be used for blocks with headers
input units cannot be defined in compact notation

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).

Units¶

Some keys have a default unit associated (not all keys have units). For such keys, the default unit is mention 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 [a.u.]

Available units:

Energy: Hartree (a.u.), eV, kJ/mol, kcal/mol, cm^-1
Length: Bohr (a.u.), Angstrom (A), nm, pm