2.1 The mandatory input files: control.in and geometry.in

As discussed in Sec. 1.5, FHI-aims requires exactly two input files—control.in and geometry.in—located in the same directory from which the FHI-aims binary is invoked. To start FHI-aims, no further input should be needed.11 1 A few specific keywords (e.g., a restart of an existing calculation from an earlier wave function or density matrix) may require additional input that simply can not be included in user-edited files. Such input files will be described with the appropriate tasks. 22 2 No command line input flags are allowed to be used with the FHI-aims executable aims.*.x, with a single exception: --version or -v. These flags will write the preamble and version information are written of the code and then stop execution. No other actions will be performed by FHI-aims in this case. No other command line flags will be honored by FHI-aims and this is by design. Communication of input should happen through control.in and geometry.in, or via a separate driver (we have several driver infrastructures). Importantly, FHI-aims can be driven (as a subroutine) by any other code that has its own input flags since the aims() subroutine in main.f90 does not check for any input flags, avoiding any conflicts with a calling code. 

# Geometry for water -- needs to be relaxed as the water molecule
# described here has a 90degree bond angle and a
# 1 Angstrom bond distance ...
atom    0.00000000    0.00000000    0.00000000    O
atom    0.70700000   -0.70700000    0.00000000    H
atom   -0.70700000   -0.70700000    0.00000000    H
Figure 2.1: Example input file geometry.in, provided with the simple test case (relaxation of H2O) described in Sec. 1.5. 
#########################################################################################
#
#  Volker Blum, 2017 : Test run input file control.in for simple H2O
#
#########################################################################################
#
#  Physical model
#
  xc                 pbe
  spin               none
  relativistic       none
  charge             0.
#
#  Relaxation
#
  relax_geometry   bfgs 1.e-2
#
################################################################################
#
#  FHI-aims code project
#  VB, Fritz-Haber Institut, 2009
#
#  Suggested "light" defaults for H atom (to be pasted into control.in file)
#  Be sure to double-check any results obtained with these settings for post-processing,
#  e.g., with the "tight" defaults and larger basis sets.
#
################################################################################
  species        H
#     global species definitions
    nucleus             1
    mass                1.00794

[...]
Figure 2.2: Excerpts from the example input file control.in, provided with the simple test case (relaxation of H2O) described in Sec. 1.5. A section of general (system-wide) run-time settings is separate from individual sections that describe settings specific to certain species (chemical elements).

Figures 2.1 and 2.2 show as examples the geometry.in and control.in files used for the simple test case (relaxation of a water molecule) described in Sec. 1.5. The philosophy of their separation is simple:

  • •

    geometry.in contains only information directly related to the atomic structure for a given calculation. This obviously includes atomic positions, with a description of the particulars of each element (or species) expected in control.in. In addition, lattice vectors may be defined if a periodic calculation is required. Any other information is only given here if it is directly tied to the atom in question, such as an initial charge, initial spin moment, relaxation constraint etc. The order of lines is irrelevant, except that information specific to a given atom must follow after the line specifying that atom, and before any following atom is specified.

  • •

    control.in contains all other runtime-specific information. Typically, this file consists of a general part, where, again, the particular order of lines is unimportant. In addition, this file contains species subtags that are references by geometry.in. Within the description of a given species, the order of lines is again unimportant, but all information concerning the same species must follow the initial species tag in one block.

In both files, the choice of units is Å for length parameters, and eV for energies; derived quantities are handled accordingly. Lines beginning with a # symbol are treated as comments, and empty lines are ignored. Finally, each non-comment line has the following, free-format structure:

  keyword value <value> <value>

Generally, all keywords and values are case-sensitive: For instance, FHI-aims will not recognize the keyword “XC” if the specified syntax is “xc”.

It is the objective of the next chapter, Chapter 3, to list all valid keywords in FHI-aims, along with a detailed explanation of their functionalities.