Geometry, System definition¶

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.

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

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:

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

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.

Force field related extensions¶

For forcefield there are two dedicated atomic attributes, the ForceField.Type and ForceField.Charge. Obviously these attributes are ignored by all other engines, although it can reduce the symmetry of the system:

System
   Atoms
      O   0.0   0.0       0.59372   ForceField.Type=O ForceField.Charge=-0.1
      H   0.0   0.76544  -0.00836   ForceField.Type=H ForceField.Charge=+0.05
      H   0.0  -0.76544  -0.00836   ForceField.Type=H ForceField.Charge=+0.05
   End
End