Geometry, System definition
***************************

The definition of the system to simulate, i.e. the positions and types
of the nuclei, the total charge, and potentially lattice vectors, is
enclosed in the "System" block:

   System header
      Atoms header # Non-standard block. See details.
         ...
      End
      BondOrders # Non-standard block. See details.
         ...
      End
      Charge float
      ElectrostaticEmbedding
         ElectricField float_list
         MultipolePotential
            ChargeModel [Point | Gaussian]
            ChargeWidth float
            Coordinates header # Non-standard block. See details.
               ...
            End
         End
      End
      FractionalCoords Yes/No
      GeometryFile string
      Lattice header # Non-standard block. See details.
         ...
      End
      Modify
         EnableAtomAttributes [gui | adf | band | forcefield | dftb | reaxff | qe]
         GuessBonds Yes/No
         LatticeStrain float_list
         MapAtomsToUnitCell float_list
         PerturbCoordinates float
         PerturbLattice float
         SuperCell integer_list
         SuperCellTrafo integer_list
         Symmetrize Yes/No
         SymmetrizeMoleculeTo string
         Translate float_list
      End
   End


Geometry, Lattice
=================

The geometry of the system is specified with the "Atoms" and "Lattice"
blocks.

"System"
   Type:
      Block

   Recurring:
      True

   Description:
      Specification of the chemical system. For some applications more
      than one system may be present in the input. In this case, all
      systems except one must have a non-empty string ID specified
      after the System keyword. The system without an ID is considered
      the main one.

   "Atoms"
      Type:
         Non-standard block

      Description:
         The atom types and coordinates. Unit can be specified in the
         header. Default unit is Angstrom.

   "Lattice"
      Type:
         Non-standard block

      Description:
         Up to three lattice vectors. Unit can be specified in the
         header. Default unit is Angstrom.

   "FractionalCoords"
      Type:
         Bool

      Default value:
         No

      Description:
         Whether the atomic coordinates in the Atoms block are given
         in fractional coordinates of the lattice vectors. Requires
         the presence of the Lattice block.

The "Atoms" block contains one line per atom, similar to the lines
found in an ".xyz" file: First the name of the element, then three
real numbers representing the coordinates of that atom in Angstrom.
The following "Atoms" block shows how one would define a water
molecule:

   System
      Atoms
         O   0.0   0.0       0.59372
         H   0.0   0.76544  -0.00836
         H   0.0  -0.76544  -0.00836
      End
   End

Note that it is possible to specify a different unit of length in the
header of the block (that is in the line after the keyword opening the
block) by putting the name of the unit in "[" and "]" brackets. So the
same water molecule could also be specified as follows:

   System
      Atoms [Bohr]
         O   0.0   0.0       1.12197
         H   0.0   1.44647  -0.01580
         H   0.0  -1.44647  -0.01580
      End
   End

Periodic systems require the specification of 1 (for chains), 2 (for
slabs) or 3 (for bulk) lattice vectors in addition to the nuclear
coordinates. Every lattice vector is specified on a separate line of
three numbers, representing the vectors x, y, and z components. Note
that for chain systems, the single lattice vector **must** point along
the x-axis, while for slab systems the two lattice vectors **must** be
in the xy-plane. Consider the following input for graphene:

   System
      Atoms
         C   0.0   0.0      0.0
         C   1.23  0.71014  0.0
      End
      Lattice
         2.46  0.0      0.0
         1.23  2.13042  0.0
      End
   End

As with the "Atoms" block, the length unit in which the lattice
vectors are given can be changed by specifying the desired unit in the
header of the block (enclosed in "[" and "]"). It is also possible to
define a system given the fractional coordinates of the atoms using
the "FractionalCoords" keyword. The numbers in the "Atoms" block are
then interpreted as fractional coordinates according to the lattice
vectors in the "Lattice" block. Note that for chain and slab systems,
the coordinates perpendicular to the periodic direction (z and y for
chains, z for slabs) are of course still in Angstrom (or alternatively
the unit set in the header of the "Atoms" block).  Using the
"FractionalCoords" keyword we could specify the geometry of table salt
(NaCl) as follows:

   System
      Lattice
         0.0   2.75  2.75
         2.75  0.0   2.75
         2.75  2.75  0.0
      End
      FractionalCoords True
      Atoms
         Na  0.0  0.0  0.0
         Cl  0.5  0.5  0.5
      End
   End

Instead of specifying the geometry of the system directly in the input
file it can also be read from an external file.

"System"
   "GeometryFile"
      Type:
         String

      Description:
         Read the geometry from a file (instead of from Atoms and
         Lattice blocks). Supported formats: .xyz

Note that the "GeometryFile" key replaces both the "Atoms" and the
"Lattice" blocks in the input. So if you specify the "GeometryFile"
keyword in the input, the "Atoms" and "Lattice" blocks must not appear
there. At the moment only the extended XYZ file format is supported.


Modifying the geometry
----------------------

Finally there are a number of keywords that *modify* the system
geometry:

"System"
   "Modify"
      Type:
         Block

      Description:
         Modifications to make to the chemical system after
         construction. This block is read like a script and the
         modifications applied top to bottom.

      "EnableAtomAttributes"
         Type:
            Multiple Choice

         Options:
            [gui, adf, band, forcefield, dftb, reaxff, qe]

         Recurring:
            True

         Description:
            Enables an atomic attribute group. This is only necessary
            if you want a group enabled, but no atom in the input is
            using any attribute from that group.

      "GuessBonds"
         Type:
            Bool

         Recurring:
            True

         Description:
            Guesses bonds based on the atomic elements and the
            geometry. Keeps existing bonds.

      "LatticeStrain"
         Type:
            Float List

         Recurring:
            True

         Description:
            Deform the input system by the specified strain. The
            strain elements are in Voigt notation, so one should
            specify 6 numbers for 3D periodic system (order:
            xx,yy,zz,yz,xz,xy), 3 numbers for 2D periodic systems
            (order: xx,yy,xy) or 1 number for 1D periodic systems.

      "MapAtomsToUnitCell"
         Type:
            Float List

         Recurring:
            True

         Description:
            For periodic systems the atoms will be moved to the
            central unit cell where all their fractional coordinates
            are in the range [start_range,start_range+1). No mapping
            will take place along non-periodic directions. If just a
            single number is given, it corresponds to start_range. If
            multiple numbers are given, they should match the number
            of lattice vectors and will be used as start ranges along
            the individual lattice vectors. If no number is given at
            all, the mapping will be done to the [-0.5:0.5) cell.

      "PerturbCoordinates"
         Type:
            Float

         Unit:
            angstrom

         Recurring:
            True

         Description:
            Perturb the atomic coordinates by adding random numbers
            between [-PerturbCoordinates,PerturbCoordinates] to each
            Cartesian component. This can be useful if you want to
            break the symmetry of your system (e.g. for a geometry
            optimization).

      "PerturbLattice"
         Type:
            Float

         Recurring:
            True

         Description:
            Perturb the lattice vectors by applying random strain with
            matrix elements between [-PerturbLattice,PerturbLattice].
            This can be useful if you want to deviate from an ideal
            symmetric geometry, for example if you look for a phase
            change due to high pressure.

      "SuperCell"
         Type:
            Integer List

         Recurring:
            True

         Description:
            Create a supercell of the input system (only possible for
            periodic systems). The integer numbers represent the
            diagonal elements of the supercell transformation; you
            should specify as many numbers as lattice vectors (i.e. 1
            number for 1D, 2 numbers for 2D and 3 numbers for 3D
            periodic systems).

      "SuperCellTrafo"
         Type:
            Integer List

         Recurring:
            True

         Description:
            Create a supercell of the input system (only possible for
            periodic systems) \vec{a}_i' = \sum_j T_{ij} \vec{a}_j.
            The integer numbers represent the supercell transformation
            T_{ij}: 1 number for 1D PBC, 4 numbers for 2D PBC
            corresponding to a 2x2 matrix (order:
            (1,1),(1,2),(2,1),(2,2)) and 9 numbers for 3D PBC
            corresponding to a 3x3 matrix (order:
            (1,1),(1,2),(1,3),(2,1),(2,2),(2,3),(3,1),(3,2),(3,3)).

      "Symmetrize"
         Type:
            Bool

         Recurring:
            True

         Description:
            Symmetrizes a system, using either the
            "symmetrize_molecule" or "symmetrize_cell" method,
            depending on periodicity.

      "SymmetrizeMoleculeTo"
         Type:
            String

         Recurring:
            True

         Description:
            Symmetrizes a molecule to a particular symmetry given by a
            Schoenflies symbol. Symmetrizes the atomic coordinates to
            machine precision, but does NOT rototranslate the molecule
            in any way. If the symmetrization fails, an error will be
            raised.

      "Translate"
         Type:
            Float List

         Unit:
            angstrom

         Recurring:
            True

         Description:
            Translate all atoms by a vector.

These modifications are applied immediately after the system block is
read. To the rest of AMS (and the input) it looks exactly as if the
modified system was specified explicitly in the "System" block input.
That means that the "SuperCell" keyword is not easily usable with
input options that require the specification of atom indices, e.g. the
constraints block. The entire "Modify" block can be read as a script:
the modifications are applied to the system in the order in which they
occur in the input. (This is important in case two modifications, e.g.
super cell building and perturbing atomic coordinates, do not commute
with each other.)


Symmetry
========

Symmetry can be used in AMS optimizations of molecules and of periodic
structures.

In case of molecules at the start of an AMS calculation one can
symmetrize an almost symmetric structure. In the Appendix Symmetry one
can find molecular orientation requirements that AMS needs such that
AMS can use the (sub)symmetry of a molecule. If the system is
symmetrized the molecular structure is rotated and translated into
this standard orientation. In the Appendix Symmetry one can also find
Schönfliess symbols for molecular point groups and symmetry labels
that are used in AMS for molecules to label normal modes.

   Modify
      Symmetrize Yes/No
   End

   Symmetry
      SymmetrizeTolerance float
      Tolerance float
   End

   UseSymmetry Yes/No

"Modify"
   "Symmetrize"
      Type:
         Bool

      Recurring:
         True

      Description:
         Symmetrizes a system, using either the "symmetrize_molecule"
         or "symmetrize_cell" method, depending on periodicity.

"Symmetry"
   "SymmetrizeTolerance"
      Type:
         Float

      Default value:
         0.05

      Description:
         Tolerance used to detect symmetry in case symmetrize is
         requested.

   "Tolerance"
      Type:
         Float

      Default value:
         1e-07

      Description:
         Tolerance used to detect symmetry in the system.

"UseSymmetry"
   Type:
      Bool

   Default value:
      Yes

   Description:
      Whether to use the system's symmetry in AMS. Symmetry is
      recognized within a tolerance as given in the Symmetry key.


Regions
=======

Some options of the AMS driver and its engines require specifying a
subset of a system's atoms. For example one might want to freeze part
of the system in a molecular dynamics calculation. We refer to these
subsets of atoms as "regions". Atoms are assigned to regions by
specifying the region names behind the atomic coordinates in the
"Atoms" block of the input:

   System
      Atoms
         C       1.22110608      -0.00000000       1.65928963     region=ring_1
         C       0.37734253      -1.16134090       1.65928963     region=ring_1
         C       0.37734253       1.16134090       1.65928963     region=ring_1
         C      -0.98789557      -0.71774815       1.65928963     region=ring_1
         C      -0.98789557       0.71774815       1.65928963     region=ring_1
         H       2.30849293      -0.00000000       1.64874914     region=ring_1
         H       0.71336355      -2.19550724       1.64874914     region=ring_1
         H       0.71336355       2.19550724       1.64874914     region=ring_1
         H      -1.86761001      -1.35689810       1.64874914     region=ring_1
         H      -1.86761001       1.35689810       1.64874914     region=ring_1
         Fe      0.00000000       0.00000000       0.00000000
         H       0.71336355       2.19550724      -1.64874914     region=ring_2
         H       0.71336355      -2.19550724      -1.64874914     region=ring_2
         C       1.22110608      -0.00000000      -1.65928963     region=ring_2
         C       0.37734253       1.16134090      -1.65928963     region=ring_2
         C       0.37734253      -1.16134090      -1.65928963     region=ring_2
         C      -0.98789557       0.71774815      -1.65928963     region=ring_2
         C      -0.98789557      -0.71774815      -1.65928963     region=ring_2
         H       2.30849293      -0.00000000      -1.64874914     region=ring_2
         H      -1.86761001       1.35689810      -1.64874914     region=ring_2
         H      -1.86761001      -1.35689810      -1.64874914     region=ring_2
      End
   End

In the above example of a ferrocene molecule, we have created two
separate regions for the two cyclopentadienyl rings. The region names
("ring_1" and "ring_2" in the example above) can be freely chosen by
the user. Note that an atom can be in more than one region, in which
case the region names should be separated by commas:

   System
      Atoms
         ...
         Mg  0.0  0.0  0.0    region=metal_centers,mol_1
         ...
      End
   End

Technically the region is handled as an atomic attribute.


Charge, atomic masses, input bond orders
========================================

AMS allows to set user-defined masses for particular atoms. This can
be used to simulate isotopes of different atoms. Masses are specified
by adding the desired mass (in Dalton) at the end of the atom's line.
The following input shows the system specification for a heavy water
molecule:

   System
      Atoms
         O   0.0   0.0       0.59372
         H   0.0   0.76544  -0.00836    mass=2.014
         H   0.0  -0.76544  -0.00836    mass=2.014
      End
   End

(Observe that the mass specified this way is an example of the atomic
attributes system.)

Finally the "System" block also contains the specification of the
system's total charge as well as optionally defined bond orders.

"System"
   "Charge"
      Type:
         Float

      Default value:
         0.0

      GUI name:
         Total charge

      Description:
         The system's total charge in atomic units.

   "BondOrders"
      Type:
         Non-standard block

      Description:
         Defined bond orders. Each line should contain two atom
         indices, followed by the bond order (1, 1.5, 2, 3 for single,
         aromatic, double and triple bonds) and (optionally) the cell
         shifts for periodic systems. May be used by MM engines and
         for defining constraints. If the system is periodic and none
         of the bonds have the cell shift defined then AMS will
         attempt to determine them following the minimum image
         convention.

The following example shows the System block with defined bond orders
for pyridine:

[image]

   System
       Atoms
          C  0.0  -1.19129014   -0.47777633
          C  0.0   1.1420834     0.90885782
          C  0.0  -1.1420834     0.90885782
          C  0.0   0.0          -1.18887601
          C  0.0   1.19129014   -0.47777633
          N  0.0   0.0           1.5894377
          H  0.0  -2.14522862   -0.99205897
          H  0.0   0.0          -2.27338592
          H  0.0   2.14522862   -0.99205897
          H  0.0   2.05492975    1.4973896
          H  0.0  -2.05492975    1.4973896
       End
       BondOrders
           1 3  1.5
           1 4  1.5
           1 7  1.0
           2 5  1.5
           2 6  1.5
           2 10 1.0
           3 6  1.5
           3 11 1.0
           4 5  1.5
           4 8  1.0
           5 9  1.0
       End
   End

Note that the specified bond orders are currently only used by the
ForceField engine and for generating distance constraints via the "All
bonds" option in the constraints block.


Homogeneous electric field and multipole charges
================================================

A homogeneous electric field and multipole charges can be requested at
the AMS level. Currently this option is supported by the engines ADF,
BAND, DFTB, MOPAC, and ReaxFF.

**Homogeneous electric field:**

   System
      ElectrostaticEmbedding
         ElectricField ex ey ez
      End
   End

"ElectrostaticEmbedding"
   "ElectricField"
      Type:
         Float List

      Unit:
         V/Angstrom

      Description:
         External homogeneous electric field with three Cartesian
         components: ex, ey, ez, the default unit being V/Å.
         In atomic units: Hartree/(e bohr) = 51.422 V/Angstrom; the
         relation to SI units is: 1 Hartree/(e bohr) = 5.14 ... e11
         V/m.                      Supported by the engines adf, band,
         dftb and mopac.                      For periodic systems the
         field may only have nonzero components orthogonal to the
         direction(s) of periodicity (i.e. for 1D periodic system the
         x-component of the electric field should be zero, while for
         2D periodic systems both the x and y components should be
         zero. This options cannot be used for 3D periodic systems.

**Point and multipole charges:**

   System
      ElectrostaticEmbedding
         MultipolePotential
            Coordinates
               x y z   q   py pz px
               x y z   q   py pz px
               ...
            End
         End
      End
   End

"ElectrostaticEmbedding"
   "MultipolePotential"
      Type:
         Block

      Description:
         External point charges (and dipoles).

      "ChargeModel"
         Type:
            Multiple Choice

         Default value:
            Point

         Options:
            [Point, Gaussian]

         Description:
            A multipole may be represented by a point (with a singular
            potential at its location) or by a spherical Gaussian
            distribution.

      "ChargeWidth"
         Type:
            Float

         Default value:
            -1.0

         Description:
            The width parameter in a.u. in case a Gaussian charge
            model is chosen. A negative value means that the width
            will be chosen automatically.

      "Coordinates"
         Type:
            Non-standard block

         Description:
            Positions and values of the multipoles, one per line. Each
            line has the following format:                         x y
            z q, or                         x y z q µx µy µz.
            Here x, y, z are the coordinates in Å, q is the charge (in
            atomic units of charge) and µx, µy, µz are the (optional)
            dipole moment components (in atomic units, i.e. e*Bohr).
            Periodic systems are not supported.

Note:

  When running geometry optimizations (or other similar tasks) in
  combination with point charges, you should be aware that the system
  might end up on top of the point charge(s), resulting in non-
  physical situations. You should consider using constraints,
  restraints or explicitly setting rigid motions options.


Load a System from file
=======================

Instead of specifying the system to simulate in the "System" block of
the input, it is also possible to read the system used in a previous
calculation from the binary ".rkf" result files of AMS. This is done
with the "LoadSystem" block in the input:

   LoadSystem header
      File string
      Section string
   End

"LoadSystem"
   Type:
      Block

   Recurring:
      True

   Description:
      Block that controls reading the chemical system from a KF file
      instead of the [System] block.

   "File"
      Type:
         String

      Description:
         The path of the KF file from which to load the system. It may
         also be the results directory containing it.

   "Section"
      Type:
         String

      Default value:
         Molecule

      Description:
         The section on the KF file from which to load the system.

Note that the "LoadSystem" block is mutually exclusive with the
"System" block: The system *either* needs to be specified in the
input, *or* loaded from a previous results file.

Any ".rkf" file written by AMS should be suitable to load a system
from. For engine output files the loaded geometry is just the one for
which the engine was invoked when it wrote this file. For the main
result file "ams.rkf" written by the AMS driver, which geometry is
loaded depends on the task that AMS was performing when this file was
written. Generally the "ams.rkf" file contains two systems:

* The input system corresponding just to the "System" block that was
  read in by AMS. This system is written to the "InputMolecule"
  section on the "ams.rkf", and can be loaded from there using the
  "LoadSystem%Section" keyword. This can be useful in order to repeat
  a previous AMS calculation for the same system, but with different
  settings, e.g. a different engine.

* The system which was the result of a previous AMS calculation, e.g.
  a geometry optimization or transition state search. This system is
  written to the "Molecule" section on the "ams.rkf". What exactly is
  considered the resulting geometry of a calculation depends in the
  task of the previous calculation. (For tasks that do not change the
  geometry (like a single point calculation) or where no configuration
  is particularly special (e.g. a PES scan), the result system is
  normally just the same as the input system.)


Atom attributes
===============

There is in general the possibility to add text after the coordinates
of an atom, we call these atomic attributes. The text should be of the
form "key=value", separated by spaces:

   System
      Atoms
         O   0.0   0.0       0.59372   key1=1 key2=y
         H   0.0   0.76544  -0.00836   file=ams.rkf
         H   0.0  -0.76544  -0.00836
      End
   End

Examples of atomic attributes are the region, and mass. The order in
which atomic attributes are specified has no effect.

In previous AMS versions, arbitrary key/value pairs would be accepted,
but only a small subset of them, such as "mass=" or
"forcefield.charge=" would have an effect. Starting with AMS2026,
there is a fixed list of allowed atomic attributes, and unknown
attributes will cause an error when the system is read in. The full
list of permissible atomic attributed can be found here.
