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
   Lattice header # Non-standard block. See details.
      ...
   End
   FractionalCoords Yes/No
   AllowCloseAtoms Yes/No
   GeometryFile string
   Symmetrize Yes/No
   LatticeStrain float_list
   SuperCell integer_list
   Charge float
   BondOrders # Non-standard block. See details.
      ...
   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 atoms, 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

It is also possible to specify the input geometry as a Z-Matrix, by putting the string Z-Matrix in the header of the block:

System
   Atoms Z-Matrix
      C
      H   1 1.089000
      H   1 1.089000  2  109.4710
      H   1 1.089000  2  109.4710  3  120.0000
      H   1 1.089000  2  109.4710  3 -120.0000
   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-component. 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
Symmetrize
Type:Bool
Default value:No
Description:Whether to symmetrize the input structure. This might also rototranslate the structure into a standard orientation. This will symmetrize the atomic coordinates to machine precision. Useful if the system is almost symmetric or to rototranslate a symmetric molecule into a standard orientation.
LatticeStrain
Type:Float List
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.
SuperCell
Type:Integer List
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
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)).
PerturbCoordinates
Type:Float
Default value:0.0
Unit:Angstrom
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
Default value:0.0
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.
MapAtomsToUnitCell
Type:Bool
Default value:No
Description:For periodic systems the atoms will be moved to the central cell.

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. Note that the randomization of the coordinates is applied after a potential supercell creation.

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 (and no symmetry is given in the System block key) the molecular structure is rotranslated 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.

System header
   Symmetrize Yes/No
   Symmetry [...]
End

Symmetry
   SymmetrizeTolerance float
   Tolerance float
End

UseSymmetry Yes/No
System
Symmetrize
Type:Bool
Default value:No
Description:Whether to symmetrize the input structure. This might also rototranslate the structure into a standard orientation. This will symmetrize the atomic coordinates to machine precision. Useful if the system is almost symmetric or to rototranslate a symmetric molecule into a standard orientation.
Symmetry
Type:Multiple Choice
Default value:AUTO
Options:[AUTO, NOSYM, C(LIN), D(LIN), C(I), C(S), C(2), C(3), C(4), C(5), C(6), C(7), C(8), C(2V), C(3V), C(4V), C(5V), C(6V), C(7V), C(8V), C(2H), C(3H), C(4H), C(5H), C(6H), C(7H), C(8H), D(2), D(3), D(4), D(5), D(6), D(7), D(8), D(2D), D(3D), D(4D), D(5D), D(6D), D(7D), D(8D), D(2H), D(3H), D(4H), D(5H), D(6H), D(7H), D(8H), I, I(H), O, O(H), T, T(D), T(H), S(4), S(6), S(8)]
Description:Use (sub)symmetry with this Schoenflies symbol. Can only be used for molecules. Orientation should be correct for the (sub)symmetry. If used icw Symmetrize, the symmetrization will not reorient the molecule.
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

The region names given by the user can then be referred to for input keywords requiring the specification of a region.

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, which might be needed by engines implementing force fields.

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. May by used by MM engines.

Note that the specified bond orders are currently only used by the ForceField engine.

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, and MOPAC.

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) = 27.211 V/bohr; 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:The charges may represented as simple points (with a singular potential at the charge location) or may represented by a spherical Gaussian distribution.
ChargeWidth
Type:Float
Default value:-1.0
Description:A 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 (in Å) and values of multipole charges, one per line. Each line describes a singe point charge like: x y z q, or x y z q py pz px. Here x, y, z are the coordinates, q is the charge (in atomic units of charge) and py, pz, px are the (optional) dipole 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

You can enter any arbitrary key/value list, but that will have no effect in general. Although there is one important effect that atoms with different atomic attributes (even unrecognized ones) are considered different elements during the symmetry detection.

The order in which keys are specified has no effect.

Examples of atomic attributes are the region, and mass.