The Engine section

The engine section specifies the engine to use for the dynamics.

Example engine section:
Engine
------
class = VelocityVerlet
timestep = 0.002

In PyRETIS, the engines are used as numerical integrators for Newton’s equations of motion. The different engines need different settings and this is specified in detail below for the different types:

Table 18 Supported engines in PyRETIS
Engine Description
Verlet Internal engine, integrate using the Verlet scheme.
Langevin Internal engine, stochastic dynamics.
Velocity Verlet Internal engine, integration using the Velocity verlet scheme.
GROMACS External engine, using GROMACS.
CP2K External engine, using CP2K.
LAMMPS External engine, using LAMMPS.
User-defined Internal/External engine, user-defined.

The Verlet engine

The Verlet engine integrates the equations of motion according to the Verlet scheme. NB: Only MD is allowed for this scheme. The engine is selected by specifying the class Verlet and the time step:

Example Engine section for Verlet:
Engine
------
class = Verlet # select Verlet integrator
timestep = 0.002  # time step for the integration

Keywords for the Verlet engine

For the Verlet engine, the following keywords can be set:

Table 19 Keywords for the Verlet engine.
Keyword Description
class Selects the Verlet engine.
timestep Defines the time step.

Keyword class

class = Verlet
The class selects the Verlet engine and it should be set to Verlet.

Keyword timestep

timestep = float

The timestep keyword defines the time step for the engine in internal units.

Default:
Not any. This keyword must be specified.

The Velocity Verlet engine

The Velocity Verlet engine integrates the equations of motion according to the Velocity Verlet scheme. The engine is selected by specifying the class VelocityVerlet and the time step:

Example Engine section for VelocityVerlet:
Engine
------
class = VelocityVerlet # select Velocity Verlet integrator
timestep = 0.002  # time step for the integration

Keywords for the Velocity Verlet engine

For the Velocity Verlet engine, the following keywords can be set:

Table 20 Keywords for the Velocity Verlet engine.
Keyword Description
class Selects the Velocity Verlet engine.
timestep Defines the time step.

Keyword class

class = VelocityVerlet
The class selects the Velocity Verlet engine and it should be set to VelocityVerlet.

Keyword timestep

timestep = float

The timestep keyword defines the time step for the engine in internal units.

Default:
Not any. This keyword must be specified.

The Langevin engine

The engine is selected by specifying the class Langevin. This is a stochastic (Brownian) integrator and a description of the implementation can be found in e.g. [1]. The integrator is fully specified as follows:

Example Engine section for Langevin:
Engine
------
class = Langevin # select Langevin integrator
timestep = 0.002  # time step for the integration
gamma = 0.3  # set gamma value,
seed = 0  # set seed for random value generator used
high_friction = False  # are we in the high friction limit?

Keywords for the Langevin engine

For the Langevin engine, the following keywords can be set:

Table 21 Keywords for the Langevin engine.
Keyword Description
class Selects the Langevin engine.
timestep Which defines the time step.
gamma Which defines the the friction parameter.
seed Which defines a seed to use for the random number generator.
high_friction Which determines if we are in the high friction limit or not.

Keyword class

class = Langevin
The class selects the Langevin engine and it should be set to Langevin.

Keyword timestep

timestep = float

The timestep keyword defines the time step for the engine in internal units.

Default:
Not any. This keyword must be specified.

Keyword gamma

gamma = float

This is the gamma parameter (\gamma, see the integration scheme) for the Langevin integrator.

Default:
Not any. This keyword must be specified.

Keyword seed

seed = integer

The seed value is an integer that is used to seed the random number generator used for the stochastic integration.

Default:
The default seed is zero: seed = 0

Keyword high_friction

high_friction = boolean

This keyword determines how the equations of motion are integrated. This is a boolean value and thus it can be set to True or False:

  • If high_friction is True, we are in the high friction limit and the equations of motion are integrated according to

    \mathbf{r}(t + \Delta t) = \mathbf{r}(t) + \gamma \Delta t \mathbf{f}(t)/m + \delta \mathbf{r},

    where \mathbf{f}(t) is the deterministic force and the displacements (\delta \mathbf{r}) are drawn from a normal distribution,

  • If high_friction is False, we are in the low friction limit and the equations of motion are integrated according to

    \mathbf{r}(t + \Delta t) = \mathbf{r}(t) + c_1 \Delta t  \mathbf{v}(t) + c_2 \mathbf{a}(t) \Delta t^2 + \delta \mathbf{r},

    where,

    \mathbf{v}(r + \Delta t) = c_0 \mathbf{v}(t) + (c_1-c_2) \Delta t \mathbf{a}(t) + c_2 \Delta t \mathbf{a}(t+\Delta t) + \delta \mathbf{v},

    and c_0 = \text{e}^{-\gamma \Delta t}, c_1 = (1 - c_0) / ( \gamma \Delta t) and c_2 = (1 - c_1) / ( \gamma \Delta t). In this case, \delta \mathbf{r} and \delta \mathbf{v} are obtained as stochastic variables.

Default:
The default setting is high_friction = False

The GROMACS engine

The GROMACS engine will use GROMACS [2] in order to integrate the equations of motion. The engine is selected by specifying the class gromacs with some additional keywords:

Example Engine section for gromacs:
Engine settings
---------------
class = gromacs
gmx = gmx
mdrun = gmx mdrun
input_path = gromacs_input
timestep = 0.002
subcycles = 3
maxwarn = 0
write_vel = True
write_force = False
gmx_format = g96

Currently, there is also an experimental gromacs2 engine implemented in PyRETIS. This engine can read the output from GROMACS on the fly, but it has not been extensively tested. It will however run faster than the gromacs engine.

Keywords for the GROMACS engine

For the GROMACS engine, the following keywords can be set:

Table 22 Keywords for the GROMACS engine.
Keyword Description
class Selects the GROMACS engine.
gmx Defines the command used to execute the GROMACS gmx program.
mdrun Defines the command used to execute the GROMACS mdrun program.
input_path Defines the folder containing the input to GROMACS.
timestep Which defines the time step.
subcycles Which defines the number of steps GROMACS will execute before we calculate order parameters, i.e. the frequency of output from GROMACS.
maxwarn Which sets the -maxwarn option of GROMACS grompp.
write_vel Determines if velocities should be written by GROMACS or not.
write_force Determines if forces should be written by GROMACS or not.
gmx_format Can be used to select the format used for GROMACS configurations.
domain_decomp Can be toggled on if domain decomposition is used in GROMACS.

Keyword class

class = gromacs
The class selects the GROMACS engine and it should be set to gromacs.

Keyword gmx

gmx = string

This keyword sets the command PyRETIS will use for executing the GROMACS gmx program. This can be used if you have different version of GROMACS installed, for instance, a single precision build named gmx and a double precision build named gmx_d.

Default:
Not any. This keyword must be specified.

Keyword mdrun

mdrun = string

This keyword sets the command PyRETIS will use for executing the GROMACS mdrun program. This can be used to execute an MPI compiled version of mdrun, by, for instance, setting: mdrun = mpiexec_mpt mdrun_mpi. Note that this command is specific to the system you are using.

Default:
Not any. This keyword must be specified.

Keyword input_path

input_path = string

This keyword sets the directory where PyRETIS will look for input files to use with GROMACS. If, for instance, input_path = gromacs-input is set, then PyRETIS will look in the folder gromacs-input relative to the directory PyRETIS is executed in.

Further, in the folder specified by input_path the following files must be present:

  • conf.g96: The initial configuration.
  • grompp.mdp: The simulation settings to use. Note that PyRETIS will alter the frequency of output and time step to match the setting given in the input to PyRETIS using the timestep and subcycles keywords. Effectively, PyRETIS will use grompp.mdp` as a template and create a pyretis.mdp, in the same folder, which is used for the GROMACS simulations.
  • topol.top: The topology for your system.
Default:
Not any. This keyword must be specified.

Keyword timestep

timestep = float

The timestep keyword defines the time step for the engine in internal units, which in this case will be gromacs units.

Default:
Not any. This keyword must be specified.

Keyword subcycles

subcycles = integer

The subcycles keyword defines the frequency of output from GROMACS and thus the frequency by which the order parameter(s) are obtained.

Default:
Not any. This keyword must be specified.

Keyword maxwarn

maxwarn = integer

The maxwarn keyword set the maximum number of warnings the GROMACS grompp command will ignore.

Default:
The default value is maxwarn = 0.

Keyword write_vel

write_vel = boolean

The write_vel keyword determines if GROMACS should write velocities when integrating the equations of motion. This can safely be set to False if your order parameter does not depend on the velocities.

Default:
The default value is write_vel = True.

Keyword write_force

write_force = boolean

The write_force keyword determines if GROMACS should write forces when integrating the equations of motion. Typically, the forces are not needed unless your order parameter depends on them.

Default:
The default value is write_force = False.

Keyword gmx_format

gmx_format = string

The gmx_format keyword specifies the format to use for GROMACS configurations. It can be set to gro or g96.

Default:
The default value is gmx_format = gro.

Keyword domain_decomp

domain_decomp = boolean

The domain_decomp keyword will execute gmx trjconv -pbc whole ... to a frame from which the system is propagated. This was implemented as some GROMACS versions did not handle bonds over periodic boundaries correctly.

Default:
The default value is domain_decomp = False.

The CP2K engine

The CP2K engine will use CP2K [3] in order to integrate the equations of motion. The engine is selected by specifying the class cp2k with some additional keywords:

Example Engine section for cp2k:
Engine
------
class = cp2k
cp2k = cp2k
input_path = cp2k-input
timestep = 0.002
subcycles = 5

Keywords for the CP2K engine

For the CP2K engine, the following keywords can be set:

Table 23 Keywords for the CP2K engine.
Keyword Description
class Selects the CP2K engine.
cp2k Defines the command used to execute CP2K.
input_path Defines the location of input files to use for CP2K.
timestep Which defines the time step.
subcycles Which defines the number of steps CP2K will execute before we calculate order parameter(s).

Keyword class

class = cp2k
The class selects the CP2K engine and it should be set to cp2k.

Keyword cp2k

cp2k = string

The command used for executing CP2K.

Default:
Not any. This keyword must be specified.

Keyword input_path

input_path = string

This keyword sets the directory where PyRETIS will look for input files to use with CP2K. If for instance input_path = cp2k-input is set, then PyRETIS will look in the folder cp2k-input relative to the directory PyRETIS is executed in.

Further, in the folder specified by input_path the following files must be present:

  • initial.xyz: A file with the initial configuration.
  • cp2k.inp: A CP2K input file, defining a MD simulation.
Default:
Not any. This keyword must be specified.

Keyword timestep

timestep = float

The timestep keyword defines the time step for the engine in internal units.

Default:
Not any. This keyword must be specified.

Keyword subcycles

subcycles = integer

The subcycles defines the frequency of the output from CP2K and thus the frequency by which the order parameter(s) are obtained.

Default:
Not any. This keyword must be specified.

The LAMMPS engine

The LAMMPS engine will use LAMMPS [4] in order to integrate the equations of motion. A description of how to use the LAMMPS engine with PyRETIS can be found in the user guide on LAMMPS.

The engine is selected by specifying the class lammps with some additional keywords:

Example Engine section for lammps:
Engine
------
class = lammps
lmp = lmp
input_path = lammps_input
subcycles = 1
extra_files = ['potential.in']

Keywords for the LAMMPS engine

For the LAMMPS engine, the following keywords can be set:

Table 24 Keywords for the LAMMPS engine.
Keyword Description
class Selects the LAMMPS engine.
lmp Defines the command used to execute LAMMPS.
input_path Defines the location of input files to use for LAMMPS.
subcycles Which defines the number of steps LAMMPS will execute before we calculate order parameter(s).
extra_files Defines the location of input files to use for LAMMPS.

Keyword class

class = lammps
The class selects the LAMMPS engine and it should be set to lammps.

Keyword lmp

lmp = string

The command used for executing LAMMPS.

Default:
Not any. This keyword must be specified.

Keyword input_path

input_path = string

This keyword sets the directory where PyRETIS will look for input files to use with LAMMPS. If for instance input_path = lammps_input is set, then PyRETIS will look in the folder lammps_input relative to the directory PyRETIS is executed in.

Further, in the folder specified by input_path the following files must be present:

  • system.data: A LAMMPS data file with the initial configuration.
  • lammps.in: A LAMMPS input file, defining a MD simulation.
  • order.in: A LAMMPS input file, defining the order parameter calculation.
Default:
Not any. This keyword must be specified.

Keyword subcycles

subcycles = integer

The subcycles defines the frequency of the output from LAMMPS, and thus the frequency by which the order parameter(s) are obtained.

Default:
Not any. This keyword must be specified.

Keyword extra

extra_files = list of strings

The extra_files defines additional files that might be needed to execute LAMMPS. For instance, may the user refer to several additional LAMMPS script in the given lammps.in file. This keyword is to make PyRETIS aware of these additional files.

Default:
None.

User-defined engines

It is also possible to extend PyRETIS with user-defined engines, written in for instance Python, FORTRAN or C. User-defined engines are specified in Python modules that PyRETIS can load and they are typically specified as follows:

Example Engine section for a user-defined engine:
Engine
------
class = VelocityVerletF
module = vvengineF.py
timestep = 0.002

Keywords for user-defined engines

Typically, the user-defined engines requires that, at least, the following keywords are set:

Table 25 Keywords for user-defined engines.
Keyword Description
class Selects the engine.
module Defines the Python file where the engine class is defined.
timestep Defines the timestep for the engine.

Keyword class

class = string
This keyword selects the engine and it should be set to the class name as it is defined in the given module.

Keyword module

module = string

This keyword specified the location of the file containing the user-defined class. This file must be accessible by PyRETIS.

Default
Not any. This keyword must be specified.

Keyword timestep

timestep = float

The timestep keyword defines the time step for the engine in internal units.

Default:
Not any. This keyword must be specified.

Additional keywords

In addition, user-defined keywords can be specified, e.g.:

Example Engine section for a user-defined engine:
Engine
------
class = VelocityVerletF
module = vvintegratorf.py
timestep = 0.002
keyword = 100
otherkeyword = 31

References

[1]M. P. Allen and D. J. Tildesley, Computer Simulation of Liquids, 1989, Oxford University Press.
[2]http://www.gromacs.org
[3]https://www.cp2k.org/
[4]https://lammps.sandia.gov/