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 [True | False]
   GeometryFile string
   LatticeStrain float_list
   SuperCell integer_list
   AtomMasses # Non-standard block. See details.
      ...
   End
   Charge float
   BondOrders # Non-standard block. See details.
      ...
   End
End

System geometry¶

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:	False
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 FractionalCoordinates 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 FractionalCoordinates 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
   FractionalCoordinates 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.

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

System

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

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.

Additional system properties¶

AMS allows to set user-defined masses for particular atoms. This can be used to simulate isotopes of different atoms. Masses are specified by tagging the specific atoms in the Atoms block and then assigning them a custom mass (in unified atomic mass units) within the AtomMasses block. The following input shows the system specification for a heavy water molecule:

System
   Atoms
      O     0.0   0.0       0.59372
      H.d   0.0   0.76544  -0.00836
      H.d   0.0  -0.76544  -0.00836
   End
   AtomMasses
      H.d 2.014
   End
End

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 (only for non-periodic systems).

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 UFF engine.

Restoring a system from disk¶

Instead of specifying the system to simulate in the System block of the input, it is also possible to restore 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.

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