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.

* Input, execution, and output section of the AMS manual

The input is usually embedded in an executable shell script. This is
the content of a typical shell script for running an 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 the command line, you should:

1. Create a text file called, for example, "test.run" and copy and
   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 *log file* "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

* Input, execution and output section of the AMS manual

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 treated 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 the 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

* AMSification of ADF


Input parsing changes in ADF2018 and later
==========================================

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


ADF2018 syntax changes 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 a *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 a *general*  |
|                                                    | key/block)                                         |
+----------------------------------------------------+----------------------------------------------------+
| ModifyStartPotential                               | ModifyStartPotential is now a block (and not a     |
|                                                    | *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 a       |
|                                                    | *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
**keyword 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 extensions of keywords.

In the example below, only the first version is allowed in ADF2018 and
later, while the second and third versions 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

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


Execution
*********

See

* Input, execution and output section of the AMS manual
