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:

The Verlet engine

The Verlet engine integrates the equations of motion according to the Verlet 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:

  • class: Selects the Verlet engine.
  • timestep: Which 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:

  • class: Selects the Velocity Verlet engine.
  • timestep: Which 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:

  • 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 force and the velocities (\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:

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

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 for instance 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 for instance be used to execute a MPI compiled version of mdrun, by for instance setting: mdrun = mpiexec_mpt mdrun_5.1.4_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 depend on them.

Default:
The default value is write_force = False.

Keyword gmx_format

gmx_format = string

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

Default:
The default value is gmx_format = g96.

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:

  • 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 Verlet 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:

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 output from CP2K and thus the frequency by which the order parameter(s) are obtained.

Default:
Not any. This keyword must be specified.

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 the user defined engines

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

  • class: Selects the engine.
  • module: Defines the Python file where the engine class is defined.
  • timestep: Defines the Python file where the engine class is defined.

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/