Documentation

TurboGAP is a program and associated collection of routines designed for carrying out atomistic calculations based on machine learning interatomic potentials. This page deals with the technical aspects of using TurboGAP; to learn more about the underlying theory, check the GAP theory page.

Calculation mode

There are two basic modes for running a TurboGAP calculation, turbogap predict and turbogap md. They are invoked by simply typing turbogap predict or turbogap md in the command line or a bash script (e.g., to run MD in parallel on 8 CPU cores: mpirun -np 8 turbogap md). Both execution modes require an input file with TurboGAP options, a gap_files directory with the GAP potential to be used in the calculation, and an XYZ file in ASE's extended XYZ format with atomic positions, lattice vectors and chemical species information (for MD, also atomic velocities are needed).

turbogap predict

turbogap predict performs single-point calculation (i.e., the atomic positions are not updated during the simulation) for total energy, local energy, forces and virial pressure. When available for the specific potential, it can also perform a Hirshfeld volume prediction. If the atoms file contains more than one configuration, in the form of concatenated individual atomic structures, TurboGAP will perform predictions for all of them.

tubogap md

turbogap md performs molecular dynamics according to the options specified in the input file.

Files

Input file (input)

The input file contains the keywords that tell TurboGAP how to perform the single-point or MD calculation requested by the user. A minimal input file (without MD options) contains only information about the structure XYZ file, the location of the potential, and chemical species. An example looks like this:

! Species-specific info
atoms_file = 'atoms.xyz'
pot_file = 'gap_files/cho.gap'
n_species = 3
species = H C O
masses = 1.01 12.01 16.00 ! this is optional for single point, mandatory for MD
e0 = 0. 0. 0. ! this is optional, to specify per-species energy offsets

For a single-point turbogap predict calculation, something like the above is all that is needed. For running MD and other specilized simulations one needs to additionally specify the appropriate keywords. Check MD options for a complete list.

Atoms file (*.xyz)

The atoms file is an atomic structure file in ASE's "extended XYZ" format. TurboGAP (currently) works exclusively in periodic boundary conditions; this must be taken into consideration when simulating molecular systems or surfaces (i.e., that an appropriate amount of vacuum is present). The format of the XYZ file must conform to the following:

Number_of_atoms
Comment line including Lattice="ax ay az bx by bz cx cy cz"
Atom_name_1   posx posy posz (velx vely velz)
Atom_name_2   posx posy posz (velx vely velz)
...
Atom_name_nat posx posy posz (velx vely velz)

where the velocity information is mandatory for MD. The positions must be in units of Angstrom and the velocities in Angstrom/fs. The TurboGAP XYZ reading capabilities are rather limited at the moment, and the information must be provided as in the example above. In the future we will fix the reding interface so that the ASE column tags in the comment line are read. For the time being, you need to stick to this format.

Potential directory (gap_files/)

The GAP potential files are usually put into a subdirectory under your working directory named gap_files. This subdirectory contains a bunch of files generated with QUIP's gap_fit program, with XML extension, as well as a mumber of other files. The XML files are often enough to run a GAP calculation with QUIP, with the notable exception of potentials with vdW corrections, which might need some preprocessing before they can be used with QUIP. The *.gap file tells TurboGAP how to use the different files to run a GAP calculation. When using these files with TurboGAP you do not need to worry about preprocessing, they're ready to go.