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

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
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 occurr 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 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.

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:

_images/pyridine.png 
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.